Deepser Deepser
  • Documentation
  • Start Free Trial
Start Free Trial
Deepser Deepser
Start Free Trial
Deepser
  • Documentation
  • Start Free Trial

Rogan Documentation

Rogan Documentation

  • Folder icon closed Folder iconDocumentation
    • Access and Visibility
      • Resources
      • Roles
      • Creating and Managing Roles in Deepser
      • Creating a new user
      • Password Reset
      • New User Registration
      • LDAP Configuration
      • SSO Deepser Configuration
      • SSO Login/Provisioning Configuration – Azure
      • Multi Factor
      • Groups
      • Groups Creation
      • Manage Users in Groups
      • Company
      • Companies in Deepser
      • Company Creation
      • Parent Companies
      • Email Domains
      • Sync Account CRM Companies
      • Advanced Sync
      • Visibility management in Deepser
      • Permission and Visibility Handling
      • Groups and Rules Definition
      • End Users Visibility Overview
      • Entities Portal Visibility
      • Empowered End User (EEU)
      • Company Supervisors
      • Additional Companies
      • Access Groups
      • Access Users
    • Activity, Worklogs & Comments
      • DeepActivity Comments
      • Placing a comment
      • Comments System Configuration
      • DeepActivity Worklog
      • Entering a Worklog
      • Enabling Worklogs in the User Portal
      • Worklog Global Grid
      • Worklog Global Grid Configuration
      • Activity Global Grid Advanced Configuration
    • Board
      • Enable groups to create boards
      • Creating a FreeForm Board
      • Creating and customizing a Lane
      • Entry Creation
      • Board Live
      • Live Board Creation
      • Advanced Live Board Configuration
      • Creating and customizing a Lane
      • Creation and Advanced Configuration of a Lane and Drop Code
    • Categories
      • Category Overview
      • Category Configuration
      • Category Usage
    • Chat
      • Using the Chat
      • Enabling the Chat on Portals
      • Chat Rooms and Moderators
      • Public Chat
      • Configure a Public Chat Widget
      • Chatbot
      • Chatbot Flow – Example
    • CMDB
      • Deepser CMDB
      • Enable CMDB in the User Portal
      • User Portal CMDB Grid Configuration
      • Advanced Configuration of CMDB Grids
      • Class, Type and Subtype
      • Configuring a CI
    • CRM
      • Deep CRM
      • Creating an account in the CRM
      • Creating a contact in the CRM
      • Creating an opportunity in the CRM
      • Contact Types in CRM
      • Opportunity Types in CRM
      • CRM Lists
      • Sync Contacts and Accounts
      • Address Functioning
      • Sales
      • Mailchimp Integration
    • Deepser API
      • API Notions
      • API Endpoint and URL
      • API Verbs and Format
      • API Authentication
      • API Main Methods
      • Retrieve
      • Multiple Retrieve
      • Create
      • Update
      • Delete
      • API Entities
      • API Company
      • User API
      • Group API
      • Service Operation API
      • Service Type API
      • Activity API
      • CMDB CI API
    • Deepser Fundamentals
      • Deepser Backend
      • Deepser User Menu
      • Deepser Navigation Menu
      • Global Search Usage
      • Deepser Home Page
      • Grids
      • Filters and Order
      • Export Data
      • Mass Action
      • Mass Action Configuration
      • Grid Creation and Cloning
      • Configuring Grids
      • Advanced Collection Configuration
      • Grids Render and Options Configuration
      • Grids Custom Options Configurations
      • Grids Renderer Tooltip Example
      • Grids Renderer Link Example
      • Grids System Configuration
      • Form Template Theory
      • FormTemplates
      • FormTemplates Structure and Buttons
      • Form Template Selection and Creation
      • Form Template Configuration
      • Form Template Structure Configuration
      • Formtemplates Fieldset Configuration
      • Formtemplates Buttons Configuration
      • Formtemplates Field Configuration
      • Advanced Form Template Rules
      • Custom Button Configuration
      • Buttons Conditional Hiding
      • User Portal
      • Browsing the user portal
      • Managing Tickets in The User Portal
      • User Portal Additional Features
      • Configuring Portal Groups
      • Configuring Portal Requests
      • Configuring Service Operations in the User Portal
      • Enabling Other Modules in the User Portal
      • Enabling Other Modules in the User Portal Grid
      • Guest Portal
      • Enabling the Guest Portal
      • Guest Portal Visibility Configuration Overview
      • Enabling Service Types on the Guest Portal
      • Adding a Portal Group in the Guest Portal
      • Adding a Portal Request in the Guest Portal
      • Editing Form Templates in the Guest Portal
      • Enabling Categories in the Guest Portal
      • Enabling Notifications for Guest Users
      • Knowledge Base in the Guest Portal
      • CMS in the Guest Portal
      • Cache Management
      • Quick Reply
      • Mentions
      • Module Creator – Creating a custom module
    • Email Integration
      • Email Integration in Service Management
      • Enable Embedded Images on Message Body
      • Mailbox
      • Configuring an Outgoing Mailbox
      • Configuring an Incoming Mailbox
      • OAuth Client for Email Integration
      • Email Loop Management Tool
      • AZURE OAUTH CLIENT
      • Google Oauth Configuration
      • Email Rules
      • Email Rule Configuration
      • Advanced Email Rule Configuration
      • Avoid Duplicate Tickets By Email
      • Managing additional Email recipients
      • Email Events
      • Enabling / Disabling an Email Event
      • Custom Email Events Creation
      • Custom Email Events Configuration
      • Attach Report to Email Notification
      • Email Templates
      • Email Template Configuration
      • New operation notification template for Requester User
      • New or Updated comment notification template for Requester
      • Email Webclient
    • Escalation
      • Escalation rule levels
      • Configuring Escalation Rules
      • Configure an escalation rule that modifies entity.
      • Escalation rule that sends an email notification
      • Create an escalation rule that is based on a metric
      • Configure an escalation rule that generates other entities
    • Importing Data
      • Import Foundamentals
      • Import Creation
      • Import Basic Data Binding
      • Import Before Run
      • Import Before Run Tutorial
      • Import Before Row
      • Import Before Row Tutorial
      • Import After Row
      • Import Binding The Unique Field “Code”
      • Import Binding the Type Value
      • Import Binding the Dates Values
      • Import Binding a Company, creating the record if it doesn’t exist
      • Global Import
    • IT Asset Management
      • IT Asset Models
      • ITAM Automatic Scan Configuration and Usage
      • ITAM Configuration
      • AnyDesk
      • Supremo
    • Knowledge Base
      • Reading the Knowledge Base
      • Knowledge Base in Service Operations
      • Article Configuration in Knowledge Base
      • Knowledge Base Configuration
      • Knowledge Base Standard Filters
      • Knowledge Base Advanced Filters
    • List
      • Introduction to lists
      • Creating a new list
      • List Values and Model Visibility
      • Use a list as the basis of a custom field
    • Password Management
      • Configuring a Password
      • Using a Password
      • Private Password
      • Password System Configuration
      • Enabling Password Manager Portal
      • Custom Deeppassword fields
      • Password Audit
    • Relations
      • Using a Relation Grid field
      • Configuring a Relation
      • Modifying relation using a custom event.
      • Opposite relation
      • Column Configuration
      • Relation Graph View
    • Service Management
      • Introduction to Services in Deepser
      • Service Operations
      • Creating a Service Operation
      • Adding Comments, Activities, Attachments and Tasks to Operations
      • Service Operation Main Fields
      • Service Operation Additional Fields
      • Service Operation Activities, Relations, Email and SLAs
      • Service Types
      • Routing rules
      • Configuring Routing Rules
      • Advanced Routing Configuration
    • SLA
      • Calendar
      • Metrics
      • Goal
    • Task
      • Creation of task type
      • Form configuration of task types
      • Task Global Grid
      • Task Global Grid Configuration
      • Task Global Grid Advanced Configuration
    • Workflow
      • Workflow Overview
      • Flow Designer
      • Flow Trigger
      • Workflow – Stage Set
      • Workflow – Executions
      • Approval workflows
      • Portal Approval Structure
      • Backend Approval Structure
      • Workflow Actions
      • Workflow Logic
      • Workflow Samples
      • Multi Stage Flow
      • SubFlow
    • Inventory
      • Inventory Overview
      • Inventory Configuration
      • Warehouse
      • Item
      • Movement
    • Custom Fields
      • Custom Field Overview
      • Custom Field – Creation
      • Custom Field – Element Type Simple
      • Custom Field – Element Type Advanced
    • Custom Event
      • Custom Event Overview
      • Custom Event – Creation
      • Custom Event – Type
    • Dashboard
      • Dashboard Overview
      • Panel Configuration
      • Chart Configuration
    • Project
      • Project Module
      • Gantt
      • Project Task
      • Resource Grid
    • Calendar
      • Calendar Configurations
      • Internal Calendar Configuration
      • Calendar Configuration Example
      • External Calendar Configuration
      • External Calendar – Google Calendar Configuration Example
      • External Calendar – Outlook Calendar Configuration Example
      • Calendar Usage
    • Survey
      • Survey Overview
      • Designer
      • Survey
      • Dashboard
    • Contract and Contract Line
      • Contracts and Contract Lines – General Overview
      • Contracts
      • Contract Lines
      • Contract Creation
      • Line Creation
      • Associate a Contract / Line with other entities
      • Contract Type
      • Line Type
      • Contracts and Escalation Rules
    • Report Documentation
      • Report Configuration
      • Report Usage
    • Sales
      • Catalog and Price List Overview
      • Catalog Configurations
      • Product
      • Price List
      • Billing Overview
      • Order Billing
      • Lines Billing
      • Worklogs Billing
      • Movements Billing
      • Operation Billing
    • Integrations
      • Teams Integration
      • NinjaOne Integration

Access and Visibility

This Course will give you a better knowledge on how Rights, Permissions and General Visibility Works in every Deepser’s Module. We will talk about Users, Groups, Roles and Companies from the System Admin Perspective.

 

Articles

  • Resources
  • Roles
  • Creating and Managing Roles in Deepser
  • Creating a new user
  • Password Reset
  • New User Registration
  • LDAP Configuration
  • SSO Deepser Configuration
  • SSO Login/Provisioning Configuration – Azure
  • Multi Factor
  • Groups
  • Groups Creation
  • Manage Users in Groups
  • Company
  • Companies in Deepser
  • Company Creation
  • Parent Companies
  • Email Domains
  • Sync Account CRM Companies
  • Advanced Sync
  • Visibility management in Deepser
  • Permission and Visibility Handling
  • Groups and Rules Definition
  • End Users Visibility Overview
  • Entities Portal Visibility
  • Empowered End User (EEU)
  • Company Supervisors
  • Additional Companies
  • Access Groups
  • Access Users

Resources

In Deepser the resources are basically the modules or service that Deepser makes available.

An example of the exposed resources is shown below.

The visibility of  the resources in Deepser can be set up to the model level.

The user will only be able to see modules and resources that have been set as visible to the membership role.

Roles

In Deepser, roles are used to define which resources the user will have access to.

We can exemplify the concept roles manage Vertical visibility in Deepser, that is, the visibility of the modules presents in the sidebar

THE MAIN ROLES IN DEEPSER AND THE PREDEFINED ROLES

The default roles in Deepser are:

RoleDescription
AdmininstratorAdministrators Users in Deepser, are users that have global access and bypass the limits of visibility in the backend, in addition to them have faculty to modify the grids and form templates. This is the only role that has access to the system configurations and the System tab.
Super AdminSuper Admins are users with Administrator role who have set “All” in the resource visibility section. This role is the only one that has access to scripting areas.
AgentsThese Users have the right to modify the grids and form templates, but they do not have access to the scripting areas or even to the modules placed in the System tab. For the rest by default, they have global access to all other modules.
Key UsersThese users are comparable to Agents users, but unlike the latter they have no ability to modify any system configuration, including grids and form templates.
UsersThese are the end users, as a rule, these users do not have access to the backend but only to the end user portal. Since they do not have access to the backend, they cannot change any system configuration or even see the tickets that have not been opened by them. If there is a need for an end user to see tickets not opened by himself, he can be modified by setting him as a Company Supervisor, in this case the user will be able to see all the tickets created by his company. Alternatively, you can configure the user as empowered user, this will give him visibility even on tickets not belonging to his company.
 

Creating and Managing Roles in Deepser

In deepser, roles are an important component in visibility management.

The roles allow you to manage the visibility of the modules accessible to user accounts (e.g. password, crm etc) or even which users can access the Deepser backend and which can only access the user portal.

Creating a Role

To create a role in Deepser you will have to go to the “System the Permissions->Roles”  menu.

At this point in the screen that will open you will have to click on the “Add New Role”

On the next screen you can set the “Role Name” field which will define the name that will have the new role.

In the type field it will be possible to define the Type that will have this role by compiling the “Type” field.

Then moving to the “Roles Resources” tab you can define which resources will be visible to the user to whom this role will be assigned by configuring the “Resource Access” field to Custom an selecting the resources you want to expose to this role.

Note: if you want to set the role to have no visibility limitations you can opt to select from the drop-down menu the item “ALL” instead of the item “Custom”, in this way no visibility limitations will be applied on the role (however this will not affect the visibility configured for groups).

Now click on the  “Apply” or on the  “Save” button.

Once the role has been created, a third item will appear in the list of tabs: Role Users.

Using this tab you can get a quick overview of all the users who have been assigned that role.

Creating a new user

A user in Deepser is an individual who interacts with the system, utilizing its features and functionalities.

To create a new user in Deepser you will need to go to the menu System  ->  Permissions  -> Users(1)

In the screen that will open, you will need to click on the “Add User” button(2)

At this point, the following screen will open:

FieldDescription
AvatarProfile picture of the user.
UsernameUsername of the user, this will serve to log in, this is a mandatory field to create and in addition this field must be unique within Deepser.
FirstnameThe name of the user. This is a required field
LastnameUser’s lastname.
EmailUser’s email
PasswordPassword of the user, note that this field is always white because the user’s password is not stored in a database format that is invertible, consequently the field remains unvalued by default even if the user has a password set, except when changing the password itself. In case of changes to this field when saving the user Deepser will automatically update the value of the password present in db.
Password ConfirmationConfirm the user’s password, like the previous field, this is also not valued except when changing the password itself.
RoleThe role of the user, depending on the role the user will have different visibilities on the various parts of the product. For example the Users role, who by default sees only the End User Portal. The roles of the users will be deepened in the dedicated Lesson, click here to go to the corresponding lesson.
ActiveIndicates whether the user is authorized to access Deepser. If the value is “Active” the user will be enabled to access, if the value is “Inactive” then the user will not be authorized to access Deepser.
Startup PageThis field indicates which is the default page to which the user will be redirected after logging in.
LocalIndicates the language in which the user visualizes Deepser interface
TimezoneIt indicates the time zone associated with that user, it is important to indicate the correct time zone so that Deepser can correctly set the format of the dates in notifications and date fields.
CompanyThe company field indicates which company the user belongs to, this field is very important since Deepser companies are one of the key elements in visibility management. The companies will be analyzed in the following lessons, click here to go to the lesson on the companies.
Additional CompaniesAdditional companies indicate to the data of which other companies the user will have access. This topic will be deepened in the lesson on company, this field will be selectable only after the user has been saved at least once
Is SupervisorThis field indicates whether the user will be a company supervisor. A company supervisor will have the ability to view and modify the tickets created by the users of his company
Company VisibilityThis field indicates if the user will have limited visibility to Company Data
Portal CMDB VisibilityThis field indicates if the user will see the cmdb in the user portal.
OTL TokenThis token if passed as a parameter (token) in the url of the request (query string) allows you to access Deepser without logging in. Note that the setting of direct access by token is by default disabled for security reasons, in addition for security reasons this token has validity of only one use, after which it is automatically reset by the system, this is done to avoid data theft.  
rp_tokenThis token is used to reset a user’s login credentials. This is a system field, at the operational level there is no use for this field.
LDAP SSO Identifier Field ValueA system field used to map the correspondence between users from AD and those from sso
API TokenThis is the “Barer Token” for access to Deepser’s A.P.I. (Application Programming Interface) To go to the course Deepser’s A.P.I. click here
EmpoweredIndicates if the user is an Empowered user, Empowered users are end users who are not limited to seeing only tickets for which they are requesters or whose company is the requesting company.

Once you have filled in the fields, you will need to click on the “Apply” or “Save” button.

Add the user directly in a group

After you have created the user you can add it directly in a group by going into the ‘’Groups’’ tab(1) and clicking Add(2).

In the following screen that will open, you will have to check the group(s) that you want the user to be added to(1) and select the action add and then submit it(2).

Then you simply have to close the window and the groups the user is included in will be shown in the “Groups” Tab.

Creating a user from an operation

Another way to create a user is directly from an operation(ticket). To do so go to the Service(1) Module and afterwards go inside a ticket.

To create a new user you have to click on the user+ icon at the Requester fieled(2) and a window will pop up. All you have left to do is fill out the necessary fields explained at the table above.

Another case is when the ticket is created with an email, without a user, like this.

All you have to do is click on the user+ icon at the Requester Field and at the window that will pop up, the email field would be automatically filled for you, so you have to complete the rest of the fields.

Note: On user creation, the default role will always be “Users” (in “Role” field), which identifies an end user. Remember to change the role according to your needs. You can check available roles here.

Create a user from CRM Contacts

To create a user from the CRM Contacts, you will have to go to the CRM module and then Contact (1). At the page that will open you have to click on the Add Contact Button on the top right of the screen(2).

Then you have to fill out the fields of the Contact Data.

The meaning of the fields is as follows:

CampDescription
NameName of the Contact
SurnameSurname of the Contact
SalutationAllows you to Pin the greeting with which Refer to the contact (e.g. Lady or Miss)
StateEnable or Disable L Account
DepartmentThe Department to which the Contact belongs
QualificationThe status of the Contact
ManagerAllows Specifying a Contact Manager
SourceIndicates the source from which the Lead was generated
RatingCustomer Account Satisfaction Level
Associate userAllows Associating Contact to a System User on Deepser
TaskTask Related to Contact

Afterwards you have to complete the information of the user at the Contacts tab and fill out the fields.

The meaning of the fields is as follows:

CampDescription
EmailEmail of the Contact
TelephoneNumber of Fixed Telephony
Mobile phoneNumber of Mobile Telephony
FaxFax of the Contact
AddressAddress of the Contact
CityCity of Contact
ProvinceProvince of Contact
CAPCap of the Contact
StateState

After you have saved the newly created contact, you have to Sync it to a user. You have to go inside the contact and click on ‘Sync User’ on top right of the screen.

Password Reset

Change Password as admin

In order to change the password any  account, you will have to go to

 System->Permissions->Users and click on the user’s account you want to change the password to.

Here you can set the new password at the “Password” field (1) and confirm the password at the “Password Confirmation” (2) and simply save the changes (3)

Reset Password

To reset password of an account you will need the email address and the username of the user you want to reset the password. In the login screen you can see at the bottom of the login ‘Forgot your password?’.

 By clicking there you will be redirected to the page where you can reset your password.

In this page you should provide username and email address of the account. After you provide the required data click the button ’Recover Password’. If the email address and the username correspond to an user in Deepser a new email should arrive at the email address provided. The email should look like the one given below:

If you click the Reset Password button or link you will be redirected to a new page where you can add your new password.

The criteria for the new password are:

  • Should be at least 7 characters
  • Should contain at least 1 letter and 1 number

After adding the password and clicking Reset Password button the password will be set to the one you provided and you will be redirected to the login page.

New User Registration

In Deepser it is possible to implement a user registration procedure to allow new users to register independently among the users present in Deepser.

Below, we will cover the procedure necessary to implement the creation of a registration form in Deepser.

CREATION OF THE NECESSARY STEPS

Deepser allows you to create a registration form by combining one or more Step components.

To create a “Step” you will need to go to the “System -> Permissions -> user Registration -> Step” menu

In the screen that will open, you will need to click on the “Add Step” button.

Once you click the button, you will be redirected to the creation screen of a new step.

Below we briefly report the meaning of each field:

FieldDescription
NameStep name
PositionPosition in the step grid.
LabelWritten that will appear to users when the step is uploaded.
Is Default stepIndicate if this is the step from which the recording will begin
Is Final stepIndicate if this is the step that will end the recording
Next stepNext step in the registration, null if the current step is the step that will end the registration
Check TokenChecks whether the verification token is present in the request.
Send TokenSubmit the verification token
Token DurationToken duration in hours and minutes
MailboxIndicates the mailbox with which the messages will be sent to the user during registration
Email EventEmail event associated with registration (if any)
StepData FormtemplateForm template associated with the current step
Validate ExpressionCustom code that allows you to validate the input data
Final MessageFinal message that will be displayed by the user if the current step is set as the final  step
Create UserIndicates whether a user will be created in this step
Create Active UserIndicates whether an active user will be created in this step
Send Reset PasswordIndicates whether a password reset email will be sent to the user
Field ConfigMapping user principal fields to form template fields
User Create ExpressionCustom code that will be used to create a user
StatusIndicates whether this step is active or not.

Registration Form Creation Example

In the successive lessons we will cover the creation of a registration form that allows a user to register himself and access the support, but only to users who belong to a company registered in Deepser, this to prevent external users from opening tickets without permission.

CREATING A CUSTOM FIELD TO RECEIVE USER INPUT

Before proceeding with the actual creation of the form, we must create a custom field that allows us to receive user input.

In the following example, we will see how to create a user only if the VAT number entered will correspond to one of the companies present in Deepser. For this example,  we will assume that there is a custom field named “cust_vat_number” that will contain the VAT number of the company.

The Custom Fields will be addressed in another lesson, to go to the lesson related to the Custom Fields click here.

To create a custom field, we must go to: System -> Custom Fields.

Here we will have to click on the model “DeepRegistration – stepData”.

On the next screen, we will have to click on the “Add Field” button.

In the screen that will be displayed, will need to fill in the fields as follows:

Important is to set the “Column Type” and “Element Type” fields to text.

At this point, you will need to click on the “Save” button

Once this is done, we can proceed to implement the registration form.

Form Creation

In order to create the Registration Form we must go to the step creation menu to create a new step.

The Step Section is located under the “System-> Permissions – > user Registration -> Step” menu.

At this point, we give a name to our registration form by entering the desired name in the “Name” field

We define the “Position” field as zero.

Now we set the label that will be displayed on the registration screen by entering the desired text in the “Label” field.

Note that this field can contain text or even html with its css styles.

We define “Is Default Step” field to yes, in this way we are defining what will be the step from which the registration will begin.

Since in our example we have only one registration step, we also define “Is Final Step” to “Yes”.

Since in our example we have only one registration step we define “Next Step” as  none, in the case of a multistep registration it will be possible to set what will be the next step, through this field.

Another important thing to notice is that to populate the field, you will first need to create a new step.

We set what will be the email box that we will use to send any Password change emails through the “Mailbox” field

Now we set which form template we want to display during registration using the field “StepData  Formtemplate”

In the “Validate Expression” field, we can go to define the custom code that we will need to carry out checks on the validity of the data passed in input.

Within this field we are going to enter the following code:

				
					/**Defining Variables**/
 
//Assigning StepDatas to a variable.
$stepData = $this->getStepdata();
 
//Assigning the value og the cust_vat_number field to a variable.
$vatNumber = $stepData->getData('cust_vat_number');
 
//Assigning the value of the email field to a variable.
$email = $stepData->getData('email');
 
//if the email isn't in a valid format return an error to the user.
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
     $this->addError("Email is not in a valid format");
}
//Retriving form the user collection all the users the have the username equivalent to the ginven e-mail.
$usersCollection = Deep::getResourceModel("deep_admin/user_collection")->addFieldToFilter("username",["eq" => $email]);
//Retriving form the user collection all the StepData the have the username equivalent to the ginven e-mail.
$stepDataCollection = Deep::getResourceModel("deep_userregistration/stepdata_collection")->addFieldToFilter("email",["eq" => $email]);
 
//If uone or more user or StepDatas where found retun an error to the user.
if($usersCollection->count() || $stepDataCollection->count()){
     $this->addError("Email Already Registered");
}
 
 
/**If the company is present in Deepser we allow the registration otherwise throw an error**/
 
//Loading a company ginven the cust_piva field, if there is non company with this field this method retrive a new object.
$company = Deep::getModel("deep_company/company")->load($vatNumber,'cust_piva');
 
//If the returned object doesen't have the id or is null,return a error to the user.
if(!($company && $company->getId())){
    $this->addError("We are sorry, but only employee of our customer can register an account");
}
				
			

In the field “Final Message” we will define the message that we will give to the user once the registration has been successfully completed.

Here, we will insert the following code:

				
					<style>
    .cust__msg{
        margin-left: auto;
        margin-right: auto;
        display: flex;
        flex-direction: column;
    }
    .cust__msg > *{
        text-align: center;
        box-sizing: border-box;
        margin-left: auto;
        margin-right:auto;
        width: 100%;
    }
    .cust__msg .row{
        display: flex;
        justify-content:space-evenly;
        padding-right: 30%;
        padding-left: 30%;
    }
 
</style>
 
 
 
<div class="cust__msg">
    <h1>Success</h1>
    <p>Congratulations, your account has been created!.</p>
    <div class="row">
        <div class="col-sm-3">
            Username: 
        </div>
        <div class="col-sm-3">
            <?php echo $this->getStepdata()->getData('email');?>
        </div>
    </div>
    <div>
        <h6>We have sent you an email with the link to reset your password.</h6>
    </div>
</div>
				
			

At this point, we will have to define to create a user by defining the field “Create User” to”Yes”.

Now, we will define if the user will be an active user by defining the field “Create Active User” to “Yes”

Now we will define whether to send the user an email at the end of the procedure that will allow him to reset the password using the “Send Reset Password” field.

Now, in the “Field Config” field we will define the mapping of the user template fields with the form fields. To add a new field to map with the form data simply click the “+” button.

We have defined the users’ field as follows:

In the “User Create Expression” field, we can define custom code that will allow us to set the user’s attributes  or in general to perform actions when creating a new user. In this field, we will enter the following code:

				
					//getting the datas from the form
$stepData = $this->getStepdata();
// assigning the end user role to the created user by passing the role id
$this->getUser()->setData("role",73);
				
			

Finally, we set the “Status” field to Enabled (If it wasn’t already set to Active).

At this point, you will need to click on the button “Save” or “Apply”

Editing the form template

To modify the form template that will be displayed during registration, you will need to click the “Preview” button

At this point, you will need to click the pencil button:

And then go to the StepData tab:

Here you can enter the fields by dragging them from the right column into the grid

Finally, you will need to click on the Save Button.

Token usage

During the registration phase it may be necessary to validate the user’s email, to do this you can send a token that will allow you to verify the user’s email.

Taking as a basis the previous example, we create another step, this time ignoring the part related to the creation of the account, in addition we will configure the sending of the token.

EMAIL TEMPLATE CREATION

In order to send the verification token to the end user it will be necessary to create an email event with its associated template form that will be used by Deepser to send the email to the user who is registering.

To create a custom mail event you will need to go to the System -> Tools ->  Email -> Templatemenu.

Then you will need to click on the “Add MailTemplate” button.

In the screen that will open you will need to define a name for the template, to do  this, simply enter the desired name in the “Name” field.

Next, we will define a code for the template, filling in the “Code” field.

At this point, it will be possible to insert in the “Subject” section the php code that will compose the subject of the email.

You can use the following code as a reference to compose the subject of the email:

				
					<?php echo Deep::helper('deep_email')->__('DEEPSER - Confirm your Registration')?>
				
			

Now it will be possible to insert in the section  “Body”, that will represent the content of the message, the PHP / HTML code that will serve to generate the body of the  mail.

You can use the following code as a reference when creating the body:

				
					<?php
$username  = $this->getModel()->getEmail();
$firstname = trim($this->getModel()->getFirstname());
$lastname  = trim($this->getModel()->getLastname());
$tmpFullname = $firstname . $lastname;
$fullname = $fullanme != "" ? $tmpFullname : "user";
$url = $this->getModel()->getTokenStepUrl();
?>
<?php $this->includeTemplate("header") ?>

<!-- Start of Main Content -->
<tr style="">
<td bgcolor="#FFFFFF" align="center" style="">
<table width="100%" align="center" cellpadding="0" cellspacing="0" border="0" class="devicewidth" style="">
<tbody style="">
<!-- Start Spacer -->
<tr>
<td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
<td class="h26" height="36" style="font-size:1px; line-height:1px;">&nbsp;</td>
<td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
</tr>
<!-- End Spacer -->
<tr style="">
<td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
<td class="mktEditable content mktEditable content" id="edit_text_1" valign="middle" style="font-family:Calibri, Helvetica, sans-serif; font-size:16px; color:#505050; text-align:left; line-height:25.6px; font-weight:normal; text-transform:none;">
<p>
<br>
<?php echo Deep::helper('deep_email')->__('Dear %s',$fullname);?>,<br>
<?php echo Deep::helper('deep_email')->__('Please confirm your registration by clicking the link below'); ;?><br>
</p>
</td>
</tr>
<!-- Start Spacer -->
<tr>
<td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
<td height="30" style="font-size:1px; line-height:1px;">&nbsp;</td>
<td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
</tr>
<!-- End Spacer -->
</tbody>
</table>
</td>
</tr>
<!-- End of Main Content -->
<!-- start of Button -->
<tr style="">
<td bgcolor="#FFFFFF" align="center" class="mktEditable" id="edit_cta_button" style="">
<table width="100%" border="0" cellspacing="0" cellpadding="0">
<tbody>
<tr>
<td class="w22" width="41" style="font-size: 1px; line-height: 1px;">&nbsp;</td>
<td align="left">
<table class="button" cellpadding="0" cellspacing="0" border="0" align="left" bgcolor="#0080ff" style="-webkit-border-radius: 4px; -moz-border-radius: 4px; border-radius: 4px;">
<tbody>
<tr>
<td width="518" align="center" valign="middle" height="65">
<span style="color: #ffffff; text-decoration: none;">
<a class="mobButton mktNoTok" href="<?php echo $url ?>" style="font-family: Calibri, Helvetica, sans-serif; font-size: 16px; color: #ffffff; display: block; height: 65px; mso-line-height-rule: exactly; line-height: 65px; font-weight: normal; text-decoration: none; text-align: center!important;" target="_blank" title="Link al ticket">
<?php echo Deep::helper('deep_email')->__('Confirm the registration')?>
</a>
</span>
</td>
</tr>
</tbody>
</table> </td>
<td class="w22" width="41" style="font-size: 1px; line-height: 1px;">&nbsp;</td>
</tr>
</tbody>
</table>
</td>
</tr>
<!-- end of Button -->
<?php $this->includeTemplate("footer") ?>
				
			

And click on the “Save”  or “Apply” button:

EMAIL EVENT CREATION

To create a custom mail event, you will need to go to the “System -> Tools ->  Email -> Event” menu.

At this point, you will need to click on the “Add Event” button.

The following page will be displayed:

At this point, it will be necessary to give a name to the event by filling in the “Name” field.

We define Whether to send attachments, changing the value of the field “Send Attachments”, in our case we set it to  “No”.

Now, in the “Email Template” field, we select the template created in the previous point of this guide.

In the “Event Trigger”section, select “DeepUserregistration-StepData”  in the “Model” field

In the “Event Expression” entry.

We insert the following code :

				
					return true;

				
			

In the “To” section

We insert the following code :

				
					/**Configuring the language with local **/
$this->changeLanguage($this->getModel()->getCustLocale());
/**Getting the email from the current model**/
$this->addTo($this->getModel()->getEmail());
				
			

At this point, we can go to click the “Save” or “Apply” button

Now the event will have been saved.

ADD A NEW FORM TEMPLATE

To create a new form template, you will need to click on “Preview”.

Here, you will need to click on the button with the arrow icon.

Now you will need to click on “New Formtemplate”

In the screen that will open, you will need to enter in the field “Enter Template Name” the name of the new form template.

Next, you will need to click on “Save”.

At this point, the new form template will be created.

SET A FIELD AS REQUIRED

To create a new form template, you will need to click on “Preview”.

Here you will need to click on the button with the pencil icon.

Here you will need to go to the “Fieldset”:  “Step data”.

At this point it will be necessary to locate the field that we want to make mandatory and click on the corresponding gear icon.

In the screen that will open you will need to change the field “Required” and set it to “Yes”.

Now you will need to click on the “OK” button on the field configuration screen.

Finally, you will need to click on the “Save” button in the form configuration window.

At this point the field will be mandatory.

EDIT FORM TEMPLATE PRIORITY

Deepser evaluates form templates from the highest priority to the lowest priority form templates.

The priority of the form templates is therefore important to define which form template the user will see.

To set the priority, you will need to go to the arrow key.

Now click on the template you want to edit.

At this point, click on the button with pencil icon.

Now you will need to click on the “Edit  Rules” button and then subsequently set a value in the  priority field.

Finally, click on the “Save” button.

STEP CREATION

For this example we will use as a basis the step created in the previous lessons, in addition we will create two form template the first named “First” with the email fields, Firstname  and  Lastname and the second named “Second” with only the  Vat  Number field (cust_vat_number) created in the previous points  of lessons of this guide.

INITIAL STEP

Let’s go to the Step section and click on the “Add Step” button

In this new we are going to configure the field “Name”, in this field we will enter the name we want to give to the step.

We configure the field “Position” to 0

We configure the field The “Label”, this field will contain the  inscription  that  the user will see when he arrives at this form.

We configure the field “Is  Default  Step”  to  “Yes”.

We configure the field “Is Final Step” to “Yes”.

We configure the “Next Step” field on the step created in the previous points (User Support Registration).

We configure the field “Check token”  to  “No”.

We configure the field “Send Token”  to  “Yes”.

We set the “Token Duration”field, to an hour or at least to the time that we believe to be sufficient to perform the registration.

We configure the”Mailbox”fieldwith the exit mailbox that we will use for registraction.

We configure the “Email Event”fieldwith  the mail event created in the point above.

At this point we set the field”StepData Formtemplate” form template that we want to use in this first step, in the template form we set all the fields that must be filled in as mandatory, in this way the user will have to fill them in order to continue, you can refer to the previous topic for the configuration of the form field as mandatory  click here to go to the guide.

To create a custom form template you can follow the guide found in the previous article, click here to go to the guide.

We can configure the fields “Create  User”  and  “Create Active  User”  to  “No”.

In the “Validate Expression” field, we insert the following code to verify the form template.

				
					/**Variables Initialization**/
 
//Assigning the stepDatas to a variable.
$stepData = $this->getStepdata();
 
//Assigning the value of the email field to a variable.
$email = $stepData->getData('email');
 
/**Verifications**/
 
//if the emil isn't in a valid format return an error to the user.
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
     $this->addError("Email is not in a valid format");
}
//Retriving form the user collection all the users the have the username equiva-lent to the ginven e-mail.
$usersCollection = Deep::getResourceModel("deep_admin/user_collection")->addFieldToFilter("username",["eq" => $email]);
//Retriving form the user collection all the StepData the have the username equivalent to the ginven e-mail.
$stepDataCollection = Deep::getResourceModel("deep_userregistration/stepdata_collection")->addFieldToFilter("email",["eq" => $email]);
 
//If uone or more user or StepDatas where found retun an error to the user.
if($usersCollection->count() || $stepDataCollection->count()){
     $this->addError("Email Already Registered");
}
				
			

In this case we can leave the field “Field Config” as we are going to manage the creation of users in the last step

We can leave the”User Create Expression”field blank because we will not create users in this step.

At this point, Click on the Apply or  Save button.

In the end, the step will be saved.

FINAL REGISTRATION STEP

Let’s move now on to the final registration step.

In this step, we are going to change the”Check  Token”field by setting it to  “Yes”.

And we will configure the form template that will be associated with this template using the field “StepData  Formtemplate”.

At this point, we modify the Form Validate Expression field to perform the only validation of the “Vat  Number” (in the case of example).

				
					**Defining Variables**/
 
//Assigning StepDatas to a variable.
$stepData = $this->getStepdata();
 
//Assigning the value og the cust_vat_number field to a variable.
$vatNumber = $stepData->getData('cust_vat_number');
 
/**If the company is present in Deepser we allow the registration otherwise throw an error**/
 
//Loading a company ginven the cust_piva field, if there is non company with this field this method retrive a new object.
$company = Deep::getModel("deep_company/company")->load($vatNumber,'cust_piva');
 
//If the returned object doesen't have the id or is null,return a error to the user.
if(!($company && $company->getId())){
    $this->addError("We are sorry, but only employee of our customer can register an account");
}
				
			

Note: this form template must have a higher priority than all the others

At this point, you will need to click on the “Save” or “Apply” button.

Enabling Registration

To enable the possibility of registering through the registration form, it will be necessary to go to the System -> Configurations  -> Admin -> Security menu.

Here you will need to change the field “Enable User Registration” and set it to “Yes”.

Now, to save the changes, you will need to click on the “Save Config”button.

At this point, the registration link will have appeared on the main Login page:

LDAP Configuration

Deepser natively supports integration with the LDAP protocol.

LDAP is a protocol for centralized resource management.

Deepser’s LDAP integration allows you to easily import users and or groups containing users that you will need to be enrolled to be managed/enabled in Deepser from an existing LDAP installation.

Note that Deepser synchronizes resources with LDAP in read-only mode and can independently manage the update of states or generally modified parameters on the LDAP Resources placed in the LDAP controller, this translates into the fact that if a user is moved to group or disabled or  in general changes are made to the user on the LDAP controller the same changes,  in a standard case, will be replicated on Deepser.

CONFIGURING LDAP INTEGRATION

To configure an LDAP integration on Deepser you will need to go to the System -> Permission  -> LDAP Integration menu

In the screen that will open, you will be able to view the LDAP integrations already configured and configure new ones.

To configure a new integration, you will need to click on the Add LDAP button.

After that the following screen will open:

Below are the fields present and their meaning:

FieldDescription
Show In LoginThis field indicates whether this LDAP integration will be visible on the login page
Is DefaultIndicates whether this LDAP integration will be the one selected by default in the list on the login page
NameLDAP Integration Name
Domain ControllerThe address at which to find the domain controller.
Cron ExpressionCron expression that indicates how often the integration will be performed.
StatusIndicates whether this integration is active or not, if it is not active the synchronization will not be performed.
Base DN  Domain base name, this field indicates the point below which Deepser will have visibility in the domain forest. 
Time-outIndicates the maximum time within which if a request is not answered, the request must be considered expired.
Use SSLIndicates whether the domain controller uses S.S.L. encryption
Use TLSIndicates whether the domain controller uses T.L.S. encryption
Follow ReferralsThis field indicates whether to follow the referral links generated by the LDAP controller. Referral links are links that indicate that the server you are    querying does not directly own the requested resource, but has a reference to the server or domain that owns that resource.
Admin UsernameUsername of the user that Deepser will use to read domain’s users.
Admin PasswordPassword of the user account that Deepser will use to read access the Domain Controller.

In the Users Configuration section, you will define how users will be synchronized in Deepser.

Below are the fields in this section and their meaning:

FieldDescription
User Name AttributeIndicates which field of the response obtained from the domain controller will contain the user’s name
User RDN AttributeThis field is the field that indicates the path relative to another entity (parent) of the resource in the Domains Forest .  ES:  distinguishedname.
User Fields  This field is used to map the relation between domain user’s fields and user’s fields in Deepser
User Object FilterThis field is used to specify an LDAP query, this will serve as a filter to retrieve only users who match the search criteria.
Account PrefixAccount prefix e.g.: “EXAMPLE\<username>”. In this case “EXAMPLE\” is the account prefix.
Account SuffixAccount suffix ex: “<username>@example.local”. in this case “@example.local” is the account suffix.
Disable UsersThis field indicates whether users created on AD as disabled should be imported as disabled or not.
Custom CodeCustom code to indicate how user field values imported from integration are assigned.

In the Groups Configuration section, you will define how groups will be synchronized in Deepser.

Below is a list of the fields present and their meaning:

FieldDescription
Group EnableThis field is used to enable  the import of groups into Deepser from the forest.
Group Base DN  Indicates which is the name of the base domain in which the groups reside (e.i.: cn=exemple,  dn=com)
Group Name AttributeIndicates which field in the object returned by the request to the domain controller will contain the name of the group.
Group Members Attribute  Indicates which field in the object returned by the request to the domain controller will contain the list of users who belong to the group
Group Object FilterThis field is used to specify an LDAP query, this will serve as a filter to retrieve only the groups that match the search criteria.
Group Fields  This field is used to bind domain group fields to group fields in Deepser

Once the fields have been configured, you will need to click on the “Save” or “Apply” button.

At this point, by clicking on the “Check LDAP” button, you can check if the integration works correctly.

If the integration works correctly, a green banner will be displayed in the upper right corner of the page.

In case of error, you will see a red banner in the upper right corner of the page.

SSO Deepser Configuration

SSO (Single Sign On) is the technology that allows you to use delegated authentication to access Deepser.

In Deepser you can configure the sso using “Google” or “Azure” as the preconfigured provider.

Alternatively, you can also configure other delegated authentication providers using the Client OAuth configurations, but in this case you will need to manually configure the authentication parameters.

Configure SSO

To configure a new ss integrationor you will need to go to the System > Tools > OAuth > Client menu

Here you will need to click on the “Add Client” button:

As a first step you will need to assign a name to the client and click on the “Save” button to get the “Redirect Uri” that will be needed to configure the provider->side SSO.

After that, you can continue the configuration.

In the screen that will open you will be able to implement the configurations to implement SSO.

Below are the fields with their meaning:

Field

Description

Name

Identification name of the OAuth Client

Status

This is the status of OAuth Client, enabled or disabled

Provider

OAuth provider. This field can take 5 values: Google, Azure, Generic, Datto RMM, NinjaOne. In case this field is set to Google or Azure it will be possible to ignore the configuration of the fields: {{Insert list of fields already configured}}. If the field is configured to Generic you will need to manually specify the configuration of the fields.

Type

This field contains all the types that a provider can have. The values present depend on the selected provider.

Tenant ID

Required for Azure provisioning provider

 

Client ID

This field must be enhanced with the client id that will be provided by the Delegated Authentication provider.

Client Secret

This Field must be configured with the client secret that will be provided by the delegated authentication provider.

Scope

This field indicates the scopes to which the client will request access to the resources. This is visible only for Generic provider.

Url Authorize

Authorization url. this parameter is the endpoint to call to obtain authorization this parameter must be provided by the authentication provider. This is visible only for Generic provider.

Url Access Token

It is the ‘URL base’ to which the parameters are added to request the authentication token (post-authorization step). You do not need to compile it for Google or Azure providers, the default values will be used. This is visible only for Generic provider.

Url Resource Owner Details

Base url of the server responsible for managing resources. This parameter must be formed by the provider. This is visible only for Generic provider.

Proxy

This field, if enhanced, will use the proxy indicated to forward requests for Delegated authentication. This is visible only for Generic provider.

Verify

If you have configured a proxy you can enable or disable SSL check. You do not need to compile it for Google or Azure providers, the default values will be used. This is visible only for Generic provider.

Scope Separator Char

Scope separator character, indicates which character the provider uses to indicate the end of one scope and the beginning of another.

At this point the client verification key will be displayed, it will be necessary to click the validate button.

At the end of this configuration, you will need to click on the “Apply” button

You will then be redirected to the login screen of the Delegated authentication provider you are configuring.

At the end of the wizard if everything went well you will be redirected to the Deepser OAuth client screen with a message that will indicate that the configuration has taken place successfully.

In case of errors on the same page the error message will appear at the top.

USER TAB CONFIGURATIONS

In this tab are the configurations related with the users either in the linked provider and in Deepser

Below are all the fields available in this section:

Field

Description

Related LDAPs

You can select one or more options from Public OpenLDAP ForumSys, Public OpenLDAP Debian.

Username Attribute

Specify which user data attribute will be used to create the username.

User Data Source

Select one of the options: Endpoint or ID Token (JWT)

Endpoint User Data

Additional information for EndPoint user data source

User fields On Creation

Is a mapping between the user fields in Deepser and the related Provision. This will be used on sign up with selected Provider or when is the first time of provision for the specific user.

User Create Expression

Is a field that accepts PHP script to do the mapping between the user fields in Deepser and the related Provision. This will be used on sign up with selected provider or when is the first time of provision for the specific user.

The default variables are:
$user => user array
$oauthUser => OAuth user array

User fields On Update

Is a mapping between the user fields in Deepser and the related Provision. This will be used every time a user signs in with the selected Provider.

User Update Expression

Is a field that accepts PHP script to do the mapping between the user fields in Deepser and the related Provision This will be used every time a user signs in with the selected Provider.

The default variables are:
$user => user array
$oauthUser => OAuth user array

Login Button Disabled

Is used to hide the login button related with the selected Provider

Login Button Caption

Is used to change the text inside the login button

Login Button Icon

Is used to change the icon inside the login button

CONFIGURE PROVISIONING 

The Provisioning functionality allows you to automatically create in Deepser the users and groups registered within your Microsoft Azure environment, if the latter have been enabled for the SSO application. 

Therefore, instead of being created/updated only at each login, it is possible to perform a synchronization between the users present in Azure who must log into Deepser, and the related User records in Deepser.  

This functionality can be performed only once, by clicking on the “Provision” button at the top right (mainly used for testing the configuration), or even be scheduled to run several times a day by configuring the Cron expression. 

To configure this functionality in Deepser, in addition to what is seen in the “Configure SSO” section, within an Azure SSO client, it will be necessary to go to the “Provisioning” tab and configure the necessary parameters. 

 

Below are the fields with their meaning: 

Field 

Description 

Provisioning enabled 

If toggled on, provisioning is enabled 

Provisioning Provider 

If “Azure” is selected,  some fields will be available

Cron Expression 

If “Azure” is selected, some specific fields will appear and others will become required 

User Provisioning Mode 

You can select the way in which users will be synchronized. Required for Azure provisioning provider. 

Disable Users 

If toggled on, local user status will be updated with provisioned user status. 

Disable Deleted Users 

If enabled, if the provided user has been deleted, or does not match the filters, or is removed from the users assigned to the application, disables the relative users in Deepser. 

User Filter 

If provisioning provider is Azure, write filters in query string format, ie: 

$filter=surname eq ‘Foo’ 

$filter=jobTitle eq null 

$filter=userPrincipalName in (“Foo”,”Bar”) 

$search=”surname:Foo” 

For documentation, see Microsoft Graph documentation 

User Group Filter 

Only provision users which are members of these specific groups. 

Groups are filtered by the field specified in Group Name Attribute 

Group Name Attribute 

Specify which group data attribute will be used as the name of the group. 

It is also the name of the group attribute to filter by in the User Group Filter and in the Group Filter.If no value is provided: Azure provisioning provider, will use displayName by default. 

Group Provisioning Mode 

You can select the way in which groups will be synchronized. Required for Azure provisioning provider. 

Group Provisioning Enabled 

If toggled on, groups will also be synchronized. 

SSO Login/Provisioning Configuration – Azure

In Deepser you can set up SSO using Azure as the default provider.

This article explains how to configure Deepser and Azure, to allow SSO and User Provisioning via Azure Account in Deepser.

It includes 3 steps:

  • Oauth client creation in Deepser: In this step we can obtain a Redirect Uri for using it in the next step (Azure Configuration).
  • Azure configuration: The configuration from provider side.
  • Oauth client configuration completion in Deepser: The completion of the Oauth client created in the first step.

Note: SSO Login can be configured only on HTTPS protocol.

Deepser Oauth Client Creation

To configure a new SSO integration you will need to go to the System >Tools >OAuth >Client menu

Here you will need to click on the “Add Client” button:

As a first step you will need to assign a name to the client and click and set the following fields as follow:

Name is the name of the oauth client.
Provider you should select Azure and type as User. The Tenant ID will be populated after you finish.

Then you can click on “Apply” or “Save” button.

After the saving you can be able to copy the “Redirect URI” from the following field:

The “Redirect Uri” will be needed to configure the provider->side SSO (Azure in our case).

So, the first step of Azure SSO Configuration in Deepser is concluded. The next steps will be Azure Configuration and then the completion of the configuration in Deepser.

Azure Configuration

In this step we can manage the configuration from provider side (Azure).

You will need to login as administrator to the Azure portal: https://portal.azure.com/.

Note: We recommend performing all configurations in incognito mode or in a browser without any active logins to Azure/Outlook 365 to avoid user conflicts during the configuration.

App Registration

Search for app registrations and open it

You can proceed with a new APP Registration (API), by clicking on “New registration” button:

On App Registration we can proceed entering the following information:

  • Name for the new App,
  • Supported Account as “Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)”,
  • Redirect URI as “Web” type (Previously generated and copied from Deepser Oauth Client) [LINK TO “Deepser Oauth Client Creation” section]

In conclusion you can click on “Register” button.

App Authentication

You can now access your newly registered application and navigate to ‘Manage > Authentication’ from the menu.

From here, you can confirm that the correct Redirect URI is set under the ‘Web’ section, and enable the following tokens:

  • Access tokens (used for implicit flows)
  • ID tokens (used for implicit and hybrid flows)

App Certificate & Secret

Under “Manage > Certificates & secrets” in the menu, you can create a secret. During the configuration process, you’ll need to set its expiration time and copy its value, which will be used later to complete the configuration in Deepser.

The copied secret value will need to be entered into the field “Client Secret” on the oauth client record in Deepser:

Notes:

  • Be sure to copy the value of the secret, not the Secret ID.
  • You must copy the secret value during the creation phase, as you won’t be able to access it later (in that case, you would need to recreate it).
  • If you set an expiration for the secret, remember to renew it before the expiration date

App Token configuration

Under “Manage > Token configuration” from menu you can set the following optional claim IDs by clicking on “Add optional claim”:

  • acct
  • email
  • family_name
  • given_name

When adding the claims, remember to check the box for “Turn on the Microsoft Graph email, profile permission (required for claims to appear in the token)”:

App API permissions

Under “Manage > API permissions” in the menu, you can add the following permissions for Microsoft Graph and then run the “Grant admin consent” action:

  • email as Delegated permission
  • offline_access as Delegated permission
  • openid as Delegated permission
  • profile as Delegated permission
  • User.Read as Delegated permission

Also at this stage, if you need to Provision user/groups in Deepser, you need to add permissions for:

  • User. Read All as Application permission
  • Group. Read All as Application permission

Click on “Add a permission” to open the permission selection prompt:

Then select “Microsoft Graph” as API permission to use:

From that screen you can choose Delegate or Application permissions and use the search field for research the desired permission to add:

After adding all desired permissions, you can run Grant admin consent command:

Enterprise Application

Now you can switch to “Enterprise Applications” by searching for it in the global search:

Then search and access your new registered application clicking on it:

After access to it, go to its properties and change the following configurations:

  • “Enable for user to sign-in” to YES
  • “Assignment require” to YES

Users and Groups

To enable provisioning for users and groups in Enterprise Application you can add your desired users and groups:

Now that everything is configured in Azure, you can go back to the Oauth Client in Deepser.

Azure > Deepser Configuration

Before going back to the Oauth Client in Deepser, we can note down all the Azure information to be used in Deepser Oauth client configuration. Below is a summary of the Azure information to be reported in Deepser:

Secret Value

The “Secret value” will be entered “Client Secret” field in Deepser (“General” Tab):

Notes:

  • Be sure to copy the value of the secret, not the Secret ID.
  • You must copy the secret value during its creation phase, as you won’t be able to access it later (in that case, you would need to recreate it).

Application (client) ID

The “Application (client) ID” will be entered “Client ID” field in Deepser (“General” Tab):

Directory (tenant) ID

The “Directory (tenant) ID” will be entered “Tenant ID” field in Deepser (“Provisioning” Tab):

Deepser Oauth Client Configuration Completion

You can now return to the Deepser Oauth Client record to proceed with the completion of configuration.

Deepser – General Tab

If not already done, please configure “Provider” and “Type” field respectively as “Azure” and “User”.

Then we can proceed to set Client ID and Client Secret:

In the “Client ID” field, enter your “Azure application ID”, which you can find in the overview section of the app registration

In the “Client Secret” field, enter the value you copied earlier when creating the secret

Deepser – Users Tab

In the “Users” tab, you will need to fill the highlighted fields:

  • Username Attribute: userPrincipalName
  • Endpoint Users Data: https://graph.microsoft.com/v1.0/me
  • Users Field: to be set as shown in the image below.

In this tab you can specify field mapping between Deepser and Azure, and you can also populate other fields and perform processing in Deepser upon creating/updating a user via the User Create Expression and User Update Expression fields.

Deepser – Provisioning Tab

If you want to enable users and groups provisioning, you can do it from “Provisioning” Tab.
In the provisioning tab you will need to fill in the fields highlighted in the figure:

In the “Tenant ID” field, enter your “Azure Directory (tenant) ID”, which you can find in the overview section of the app registration (like the Client ID):

After completing the configuration, you can return on the “General” Tab, and click on the “Validate” button and check if the connection between Deepser and Azure works well.

Note: We recommend performing validation in incognito mode or in a browser without any active logins to Azure/Outlook 365 to avoid user conflicts during the configuration.

For doing this, you can copy validation URL directly from “Redirect URI” field:

By clicking the provision button, you can check the configuration, and the users/groups selected in the Azure app should now correctly imported into Deepser.

You can also configure a Cron Expression to automatically run the provisioning at scheduled times.

Also refer to this article, for a better understanding of the fields in this form.

Multi Factor

Multi-factor authentication (MFA) is a security system that requires multiple forms of verification to authenticate a user’s identity and grant access to a system. Instead of relying solely on a password, MFA typically combines something the user knows (like a password) with something they have (such as a smartphone or email address for receiving a code).This layered approach significantly enhances security by making it harder for unauthorized users to gain access, even if they obtain one factor of authentication.

Multi Factor Configuration

To go to the Multi Factor Configuration you will need to go to the

System->Tools->Multi Factor->Configuration

To create a new one you will need to Click on Add Configuration button on the top right of the screen.

The following screen will open:

Field Name

Description

Name

Name of the Configuration

Type

Type of the Multi Factor Authentication TOTP(APP) or Email

Enable Groups

Groups that will be able to use Multi Factor Authentication

Label

Configuration’s Label that will be shown on the app

Status

Enabled or Disabled. Weather the session is enabled or disabled.

Note: Both types of Multi Factor Authentication are suggested to be enabled in order to deal with unforeseen events(such as phone out of charge or unable to access email).

Enabling Email MFA in Deepser

Email MFA(Multi Factor Authentication) is possible in Deepser. In order to enable it you will have to choose the type Email in the Multi Factor Configuration.

Field Name

Description

Name

Name of the Configuration

Type

Type of the Multi Factor Authentication TOTP(APP) or Email

Enable Groups

Groups that will be able to use Multi Factor Authentication

Status

Enabled or Disabled. Weather the session is enabled or disabled.

Mailbox

The configured mailbox that will be used to send out the code via email

Mail Template

The email template that will be received via email

Token Valid Time

The time that the received code is valid for

After all of the fields are completed, whenever you try to log in the code will be sent to the email of the account.

Now every time you try to log in you will have to enter the MFA code received via email.

Depending on how you have configured the email template, this is how it will look like on the email.

In case you fail to insert the code within the chosen Token Valid Time, the following screen will appear which notifies you.

Useful guides: Out-going mailbox , Email Templates , OAuth Client for Email Integration

Enabling APP MFA in Deepser

In order to activate the MFA in deepser you will need to go to your account settings.

Afterwards you will need to go the Security tab.

To enhance security, Deepser utilizes multi-factor authentication (MFA), which integrates an additional verification step involving a secondary device, typically a mobile phone.

You can verify your identity using an authenticator app like Authy, Google Authenticator, Microsoft Authenticator. For this guide, we are going to use Authy.

Scan this QR code through the app; it will display a 6 digits code which you need to enter below to enable login by app.

Using Authy App, you will have to Add An Account and then scan the QR code shown on account settings of deepser.

After you have scanned it, you would be able to see the configuration settings you set before, which you can also change whenever you need to from deepser or through the app.

After you have saved the settings, the 6 digit code will appear on your mobile screen, which you are required to enter in the Account Security Field.

And after the correct code has been set, you have to click on Verify and the following screen will appear:

Now every time you try to log in you will have to enter the MFA code in the authentication app.

Please note that each verification code generated for Deepser’s multi-factor authentication (MFA) remains valid for 30 seconds, after which a new code is automatically generated.

Authentication Request

Each request for log in is stored and saved in Deepser. You can view it by heading to

 System->Tools->Multi Factor->Authentication Request.

Field Name

Description

User

The user that requested to log in

Session ID

Unique ID for each log in session

State

Shows if the log in was verified or not

Generated At

The date and time the request was generated

Attempts

How many times did it take for the user to set the correct authentication code

Last Attempt At

Date and Time the user last tried to log in

Last User Agent

Web Browser or Application that was most recently used to access Deepser

Last IP Address

Numerical Label of the most recent device network that was used to access Deepser

Status

Enabled or Disabled. Weather the session is enabled or disabled.

Groups

Once the Users are created, Deepser allows you to organize them into Groups.

Groups are intended as work groups of backend user (Key-User, Agent, Admin) or End-User. A user can be part of several groups.

In Deepser, through groups, you can manage two fundamental aspects: record assignment and visibility.

RECORD ASSIGNMENT

Once the group configuration is complete, records can also be assigned to groups.

For example, in the Service module, we can define the assignee group of a request.

Once the group has been selected, even the select-box with the users assigned to the record is automatically filtered according to the members of that group.

RECORDS VISIBILITY/MODIFICATION/DELETION PERMISSIONS

 Deepser allows you to filter, according to the groups to which the user belongs, the resources he can access.

It also allows you to define which permissions (visibility, modification, deletion) on records have the different teams of users within the modules they can access.

Groups Creation

To create new groups in Deepser, or manage existing ones, go to the menu item System-Permission-Groups. This menu is accessible only by Administrator role user.

At this point the main grid of the groups will be shown.

To add a new group click on the button (top right, circled in the picture) ‘+ Add Group‘.

 

At this point the group creation form will open.

The fields of the form have the following meaning

FieldMeaning
NameThe name of the group, displayed inside the select-boxes and grids in the system.
StatusIndicates whether or not the group is active in the system.
EmailThe group email (if any), to send automatic notifications to the email box dedicated to the team.
LevelThe level of support of the group. It is a useful number for Service Desk measurements and automation. For example, if you want to measure the working time of all top-level support teams, set level 1 to all top-level support groups in your organization.
Company VisibilityA user who belongs to a group with this field enhanced sees only the data of his company or sub-companies. In the case of a user with User type, this field is by-passed, because the user sees only the data of his Company.   Note: the same field is also present in the individual user form, so the system will first try to apply the setting at the user level; if it is not set, apply the setting at the group level.
DescriptionThe description of the group. Data used to keep internal notes on the configuration or meaning of the group.

Manage Users in Groups

ADD USERS TO GROUP

To add users to a group, after you’ve created it, click on the Members tab, in the group configuration form.

At this point a grid (Relation Grid) will be shown, containing all users already present in the group (if the group has just been created it will obviously be empty).

Click on the Add button to open the popup with the list of users in the system.

To add one or more users to a group simply follow these 3 steps.

  1. Select users using the checkbox on the left.
  2. Select the Add item in the Select at the top right.
  3. Click the Submit button to finish entering the system.

REMOVE USERS FROM A GROUP

To remove users from a group click on the Members tab, present in the group configuration form.

At this point a grid (Relation Grid) containing the users present in the group will be proposed.

To remove one or more users from a group simply follow these 3 steps.

  1. Select users using the checkbox on the left.
  2. Select the Delete item in the Select at the top right.
  3. Click the Submit button to finish entering the system.

Company

In Deepser companies are important to manage visibility as users with the exception of empowered Users will be able to see only tickets, there but more generally all entities only if they are assigned or belonging to the company of which they are part.

In Case a user is a business supervisor and he is assigned to the Additional companies he will see all the entities belonging or assigned to the Additional Companies.

Users whose company is the parent of other companies, think for example of a company that is the parent company, will be able to see the entities connected or belonging to the daughter companies if and only if the “Limit to Company Data” field is not configured in the user’s configuration to “Company Data”.

Companies in Deepser

As mentioned in the introductory article of this lesson, companies have an important role in managing visibility.

In this article, we will analyze in the Deepser entities the ways in which the Corresponding Companies are associated.

THE CI

Companies in Deepser can be both assignees of a ci and owners of a ci.

If the company is assignees of a ci (figure 1) then it means that the users of that company or of the subsidiary companies will be able to see and interact with that ci  (place  there is no limitation of visibility for groups defined at the level of cmdb).

If the company owns a ci (Figure 2), users of that company will be able to see and interact with the ci in question.

Note that the visibility of the ci is evaluated in “or“ between the owner companies and the assignee companies

Tickets

Companies play a fundamental role in ticket management as  they are evaluated by Deepser to determine which tickets will be viewed by a  given  user (End User), however if  the  user in question is not a  Company  Supervisor or an Empowered User  and is an End User, it will only see the tickets created by him, also Agents, Key Users and even Administrators could be limited to view the company datas, in this case they will see only the tickets created by their company in the user portal and in the backend.

Contacts and CRM items

In Deepser you can associate a company with an account in the CRM, or create a company from a CRM account.

The Accounts in the CRM serve as an address book and allow you to enter contact information related to the company.

Contracts

In Deepser it is possible to create contracts and associate them with a company, it can be  the owner (Fig. 1) or  assignee of the contract  (Fig. 2), in this way it will be possible to automatically manage the costs  related  to a supplier company  or the costs related to the assistance lines, for example it is possible to automatically manage the total number of hours of assistance and the total number of hours spent by a customer company.

For a more in-depth analysis of the contracts in Deepser  please check  the corresponding section of the documentation; to go to the corresponding section  click here.

Company Creation

In Deepser you can create new companies by going to the menu: System -> Companies.

Here you can create a new company using the “Add Company” button

At this point, the following screen will open:

Below is the list of fields and their meaning:

FieldDescription
Parent AccountThis field indicates which is the parent company of the company that is  configured, if the  company will not have any parents then you will need to set the field as empty.
NameName of the company you are configuring
DescriptionDescription of the company you are configuring
PhonePhone of the company you are configuring
FaxFax of the company you are configuring
AddressAddress of the company you are configuring
CityCity of the company you are configuring
AreStatus (geographical/political) of the company you are configuring
CountryCountry of the company you are configuring
Zip CodePostal Code of the company you are configuring
NotesNotes about the company you are configuring
Email DomainsEmail domains associated with the company. Through this field it is possible to associate one or more email domains so that if one never, is received from one of these domains it is associated with the correct company.
LogoLogo of the company you are configuring
Primary ContactUser who will be used as primary contact by Deepser, this will be the reference user  for this company
StatusIndicates if the company is active or not, if it is not active it will not be displayed among the possible choices in the Company comboboxes.

At this point, it will be sufficient to click on the “Save” or “Apply” button to save the changes and create the company.

Parent Companies

Parent Companies in Deepser are companies that are referred to as relatives in related companies and that do not have a parent company themselves.

Companies’ Supervisor users who belong to the parent company if not limited to viewing only company data will also have visibility on the entities that belong or are assigned to the subsidiaries.

A company can have only one parent company, while a parent company can have several subsidiaries companies.

Creating a parent company

To make a company a parent company, you will need to go to the System -> Companies menu.

At this point, we must enter into the modification of a company that will become a subsidiaries company.

At this point it will be necessary to modify the “Parent Account” field, here we will select the company that will become the parent company.

At this point, you will need to click on the “Save” or “Apply” button

Now the company will be saved.

Email Domains

In Deepser you can associate a domain with a company.

In this way, when Deepser receives an email from an unregistered user but with a domain associated with a company, Deepser will associate automatically that email with the correct company.

ADD AN EMAIL DOMAIN TO A COMPANY

To add an email domain, you will need to go to the menu: System -> Company

At this point, we click on the company to which we want to associate the domain or domains.

 

To this point we go to the “Email Domains” field, here we click on the “+” button.

In the text field that will appear we enter the domain in the form: “domainname.ext” for example: “example.com”.

Now is possible to proceed in the same way for all the domains that we want to associate with this company.

Once finished, you will need to click on the “Save” or “Apply” button.

In the company will be saved, and the emails received from these domains will be associated with the company.

Sync Account CRM Companies

In Deepser you can create a company starting from an account on the CRM.

This allows you to automatically transform also reporting the data entered in the account in the company model.

Note, however, that not all fields are synchronized automatically, for example the custom fields are not natively reported, to overcome this you can define an advanced synchronization procedure that we will deal with in the next topic.

SYNCHRONIZE CRM ACCOUNT WITH COMPANY

To synchronize a CRM Account with a company, you will need to go to the CRM -> Account entry.

Here, you will need to click on the Account you want to turn into a Company.

In the screen that will open, you will need to click on the “Sync Company” button located in the upper right corner.

In the popup that will open you will have to be asked if you are sure to proceed, you will need to click on the “Yes” button to create the company or on the “Cancel” button to cancel the operation.

At this point, the new company will be created.

Note that if there is already a company with the same name as the Account it will not be associated with the existing company, but another one will be created associated with this crm account.

Advanced Sync

In Deepser it is possible to configure an advanced Synchronization procedure that allows you to set  in the created company the  fields  that the Standard synchronization process would not import  (e.g.  custom fields).  

In this guide we will see how to implement this procedure through custom events, we will see the creation of a unilateral synchronization procedure that is, the updates will be implemented by taking the changes from the CRM accounts and transporting them to the companies.

Note that advanced synchronization is an extension of the synchronization process and onventional, not a substitute for it,   so before the changes implemented in this guide take effect you will need to carry out the conventional synchronization process.

Creating a custom field

Before proceeding with the actual creation of the form, we must create a custom field that allows us to receive user input.

For custom fields will be addressed in a special lesson, to go to the lesson related to custom fields click here.

To create a custom field we must go to: System -> Custom Fields.

Here we will have to click on the desired model, in our example “DeepCrm – Account”.  

On the next screen we will have to click on the “Add Field” button

On the next screen you will need to fill in the fields as follows:

Important to set the “Column Type” to text and the “Element Type” to text.

At this point you will need to click on the “Save” button

Once this is done we can proceed to implement the real registration form.

ADVANCED ACCOUNT TO COMPANY SYNC EXAMPLE

In the following example we assume that there is both on the model “DeepCrm – Account” and on the model “DeepCompany – Company” a custom field of type text containing the VAT  number.

The field on the model “DeepCompany – Company” named  ” cust_vat_number “.
The field on the model “DeepCrm – Account” named “cust_vat_number”. 
Logically it is possible to define any field following this example as a starting point.

To implement create a custom event for advanced synchronization you will need to go to  the menu: System- > Custom Fields.

Here you will need to go click on the “DeepCrm Account” template.

At this point it will be necessary to click on the “Events” item.

In the screen that will open you will need to click on the “Add Event”button.

Now the following screen will open:

Here we are going to fill in the “Name” field with the name we want to assign to the event.

We set the Type field to “After Save”.

Now fill in the “Method” field with the following code:

				
					/** Verify if the account is synched**/
if($this->getSynced() && $this->getCompanyId()){
    /**Load the company from given the company id**/
    $linkedCompany = Deep::getModel('deep_company/company')->load($this->getCompanyId());
    /**If the company exist and the company have an id set, set the sync data, otherwise, do nothing**/
    if($linkedCompany && $linkedCompany->getId()){
        /**Load the custom field from the Account and insert it in to the company**/
        $linkedCompany->setData("cust_vat_number",$this->getData('cust_vat_number'));
        /**After the valorization of all the fields call the method Save on the company object to update the ditas on the Database**/
        $linkedCompany->save();
    }
}
				
			

Finally, must click on the “Save Event” button or the “Save And Continue  Edit” button.

Now when we are going to sync  a company he custom fields that we have indicated will be synchronized.

Visibility management in Deepser

In Deepser visibilities are managed through 4 main elements:  The “Requester” field, Roles, Companies and Groups.

Below, we will cover each of these aspects in more detail.

THE REQUESTER FIELD

The requesting field indicates who requested the Ticket, this field is used by Deepser to set the visibility of the Tickets for the End Users, unless the user is a Company Supervisor or an Empowered User.

ROLES

In Deepser, roles are used to define which resources the user will have access to.

We can exemplify the concept of managed roles with vertical visibility in Deepser, that is, the visibility of the modules presented in the sidebar

THE MAIN ROLES IN DEEPSER AND THE PREDEFINED ROLES

The default roles in Deepser are:

Role Description
Administrator Users administrators in Deepser, they have global access and bypass the limits of visibility in the backend, in addition to this they faculty to modify the grids and form templates. This is the only role that has access to the system configuration and the System tab). Note: Super Admin users are Administrators who have set “All” in the resource visibility section. This role is the only one that has access to scripting areas in Deepser.
Agents These Users have the right to modify the grids and form templates, but they do not have access to the scripting areas or even to the modules placed in the System tab. For the rest by default they have global access to all other modules.
Key Users These users are comparable to Agents users, but unlike them, they have no ability to modify any system configuration, including grids and form templates.
Users These are the end users, by default, these users do not have access to the backend, but only to the end user portal. Since they do not have access to the backend they cannot change any system configuration or even see the tickets that have not been opened by them. If there is a need for an end user to see tickets not opened by himself it can be modified by setting it as a Company Supervisor, in this case the user will be able to see all the tickets that belong to his company. Alternatively you can configure the user as an empowered user, this will give him visibility even on tickets not belonging to his company.

COMPANIES

At Deepser, companies are very important for managing visibility.

In Deepser a company represents a company in reality, or it can represent a department (in the case for example of a very large and structured company).

Companies limit the visibility of tickets or entities to the extent that entities created and by a company are generally only visible to users of that company or users who have that company among the additional companies.

All users who try to open a ticket or generally interact with an entity that does not belong to their company would get the “Access Denied” error.

GROUPS

Groups in Deepser allow you to manage entity visibility for groups of users.

For each Deepser entity, it will be possible to define which groups will have visibility on that resource. For all other groups, it will not be visible.

It is also important to note that in addition to groups it is possible to specify on the resource also the pseudo group “All Groups”, as the name suggests this group makes the resource visible to all groups.

If a user belongs to multiple groups, one of which has visibility and one of which does not have it, then the resource will be visible.

Permission and Visibility Handling

VISIBILITY MANAGEMENT

In Deepser it is possible to manage the user visibilit on the entities through two additional systems: Roles and Groups.

The Roles allow you to manage visibility vertically, preventing the access access to entire modules (Service, CMDB, CRM etc.) or areas (System submenu) of Deepser.

The Groups instead allow to manage the visibility in a horizontally.

On them is based the visibility, for example, of:

  • Types of Service
  • Visibility of individual Operations (through group rules)
  • CMDB classes
  • Types of Contacts
  • Any standard grid in Deepser
  • Visibility or possibility to modify fields in Form Templates
  • Email Notifications (notifications to entire groups)

PERMISSION MANAGEMENT

You can configure specific rules for each group to manage the permissions that users have on Deepser entities.

The Permissions on which the rules can be defined are the following:

PermissionExplanation
CREATEIndicates whether the user can create records for a given entity. Normally, the conditions in this case are simply true or false or indicate whether a user can create that record.
READIndicates whether the user can view the details of records for a given entity. In this case, you can define custom expressions to filter visibility on certain record types. For example, we can define that users in a group can display Service Operations, but only those of a certain Service Type. Or we can define the scenario where a user group can only display the Service Operations assigned to the users in the group.
UPDATEIndicates whether the user can edit records for a given entity. In this case, you can define custom expressions to filter the change for certain record types. For example, we can define that users in a group can modify Service Operations, but only those of a certain Service Type. Or we can define that a user group can modify only the Service Operations assigned to the users in the group.
DELETEIndicates whether the user can delete (physically delete) records for a given entity. In this case, you can define custom expressions to filter the deletion for certain record types. For example, we can define that users in a group can delete Service Operations, but only those of a certain Service Type. Or we can define that a user group can only delete the Service Operations assigned to the users in the group.
GRIDIndicates whether the user can view records, in the grids, for a given entity. In this case, you can define custom expressions to filter the display for certain record types. For example, we can define that the users of a group can display in the grids only the Service Operations assigned to the users of the group. With this permission you can filter “upstream” the queries made by Deepser’s grids, filtering them for each specific user group and separating the visibility of your service records for individual teams.

To configure permissions from the group configuration menu access the Rules tab.

A list of any rules already configured for that group will appear.

From here you can add new rules or remove already defined ones.

By clicking on the + button the form for adding a new rule will appear.

The form fields have the following meaning

FieldMeaning
ModelModel on which to define a rule/permit.
TypeType of permission for which define the rule: Create, Read, Update, Delete, Grid.
ExpressionPHP scripting area where you can define the rule by code.
AllThis option enables permission (Type), to all members of the current group, on all model entities.
Assigned to UserThis option enables permission (Type), to all members of the current group, on all entities of the model (Model), of which the User is the Assignee User.
Assigned to User GroupsThis option enables permission (Type), to all members of the current group, on all entities of the model (Model), which have the current group as the Assignee group.
User is RequesterThis option enables permission (Type), to all members of the current group, on all entities of the model (Model), of which the User is the Applicant.

Note1: if a group has no rules configured for some models then that group has read / display / write / delete privileges on all records of those models. For this reason it is always good to set the permissions within the groups whose privileges you want to restrict.

Note2: If a user belongs to several groups, which have different rules, the most restrictive one is applied, case by case.

Groups and Rules Definition

It is possible to define using PHP code, rules for the management of permissions, from the simplest to the most articulated.

Once positioned in the Rules configuration form, expand the scripting area by clicking on the </> icon G Expression field.

Inside that you can define a rule using PHP code.

EXAMPLE – DEFINE A SET OF CUSTOM RULES FOR A GROUP

In this example you want a group of users to be able:

  • Create Service Operations;
  • Delete only the Service Operations assigned to your user (Assigned To);
  • Modify Service Operations sent by a specific user group;
  • View details only of the Service Operations assigned to your Assigned Group;
  • Display in the grids only the Service Operations assigned to your user groups (Assigned Group).

To accomplish this requirements, you need to define 5 distinct rules.

RULE 1: MANAGE CREATION

To allow users to “CreateService Operations” it is necessary to define a rule having Create Type, DeepService-Operations Model and than insert the following PHP code:

				
					return true;
				
			

RULE 2: MANAGE CANCELLATION

To allow users to “Delete only the Service Operations assigned to their user” it is necessary to define a rule on the DeepService-Operations Model withType Delete where verify the current user is also the assigned user of the operation.

To do this, insert the following code:

				
					//retrieve the assigned user username
$assignedUsername = $model->getAssignedUsername();
//retrieve the current user
$currentUser = Deep::helper('deep_admin')->getCurrentUser();
//ticket has an assigned user and assigned user is the current user then allow delete action
if ($assignedUsername && $assignedUsername == $currentUser->getUsername())
    return true;
 
return false;
				
			

RULE 3: MANAGE EDITING

To allow users in the group to “Modify Service Operations sent by a specific user group” it is necessary to define a rule on the DeepService-Operations with Update Type to verify that the Requester of an operation is a member of a specific group.

To do this, insert the following code:

				
					//retrieve the requeter user obkject instance
$requester = $model->getRequesterUser();
//if requester user is member of customers group then allow the update action
if ($requester && $requester->isInGroup('Customers'))
    return true;
 
return false;
				
			

RULE 4: MANAGE THE DISPLAY

To allow users to “View details only of the Service Operations assigned to their own user groupsyou need to define a rule on the DeepService-Operations Model of Type Read to verify that the current user belongs to the assigned group.

To do this, insert the following code:

				
					//retrieve the assigned group id
$assignedGroup = $model->getAssignedGroupId();
//retrieve the current user
$currentUser = Deep::helper('deep_admin')->getCurrentUser();
// if the current user is a member of the assigned group then allow to view operation details
if ($assignedGroup && $currentUser->isInGroup((int)$assignedGroup))
    return true;
 
return false;
				
			

RULE 5: MANAGE THE DISPLAY IN GRIDS

In order to allow the users to “Display in the grids only the Service Operations assigned to the groups of which the members are member of” you need to define a rule on the DeepService-Operations Model of Grid Type to verify that the current user belongs to the assigned group.

In this case, acting on the grid, add a filter to the query that retrieve records from the database.

				
					//retrieve the assigned user
$currentUser = Deep::helper('deep_admin')->getCurrentUser();
//add a filter to the DB query on assigned group
// assigned group must be in the array returned by $currentUser->getGroupIds()
$collection->addFieldToFilter(
    'assigned_group_id', ['in' => $currentUser->getGroupIds()]
);
				
			

End Users Visibility Overview

In Deepser, end users correspond to those users whose role is configured as users.

They have access only to the user portal and possibly, if enabled, to the public portal, only if enabled.

TICKETS

End users can see only the tickets opened by them, unless they are Company Supervisors or Empowered Users.

In the case of an End user who is also a Company Supervisor, he will have access to all the tickets of his Company and all the tickets of the Additional Companies unless the user is limited to the Company Data, in this case he will have access only to his Company Ticket.

CIs

End users can view the CI assigned to them or of which they are the owners and which they belong, in the case of Corporate supervisor users they will view all the CI of their company.

FORMS

End users do not have the right to modify form fields or change the form currently displayed.

Entities Portal Visibility

For the management of modules related to the End-User Portal, it is possible to intervene through configuration to change the display/management of the modules directly from the “Configuration” section of the “System” menu:

By clicking on “Portal Configurations” you will be able to manage the following modules:

Activity – Worklog visibility

For the visibility of the Activity module in the Deepser user portal, it is possible to act by configuration by going to “SYSTEM > Configuration > Portal – Configurations” and finally Activity, we will access the Deepser section dedicated to configuring the visibility of the Activity module on the portal side:

Inside we will find the following configurable fields:

  • Show Worklogs: Which allows you to view worklog records on the end-user portal side.
  • Add/Edit Worklogs: Which allows end users to edit or add new worklogs.

 

Worklog visibility is based on the entity it relates to. If the user has visibility for that specific entity then he can also see the worklogs if added to the form template.

 

CMDB – CIs Visibility

For the visibility of CIs in the Deepser user portal, we can act in different ways.

First of all, going to “SYSTEM > Configuration > Portal – Configurations” and finally CMDB, we will access the section of Deepser dedicated to configuring the visibility of the CMDB on the portal side:

From here we can act on the configuration:

Enable: Allows you to enable or disable the visibility of the CMDB on the portal side.

Enable Priority: Allows you to choose how you want to manage the visibility of your CIs on the portal side.
The selectable values will be:

  • Global: Which allows the CMDB module to be displayed to all end users without distinction.
  • Users: Which allows the CMDB module to be displayed only to end users who have the “Portal CMDB Visibility” field set to “Yes” in their master data (accessible from System > Permissions > Users).

Once the CMDB module display type has been enabled and configured, the display of individual CI records will be managed based on the following fields:

  • Owner Company – if the company of the user is the owner company
  • Owner Group – if the user is part of the owner group
  • Assigned User – if the user is assigned user for that entity
  • Status – if the status of the entity is active

CRM – CRM Modules Visibility

For the visibility of CRM modules in the Deepser user portal, it is possible to act by configuring by going to “SYSTEM > Configuration > Portal – Configurations” and finally CRM, we will access the Deepser section dedicated to configuring the visibility of the CRM on the portal side:

From here it will be possible to indicate which modules in the CRM section must be made visible on the portal side (Enable Account, Enable Contact, Enable Opportunities fields).

You can also specify which groups will be able to access these modules, or whether all users will be able to access them indiscriminately (by selecting All groups).

 

Once the CRM forms section is enabled and configured, the display of individual records will be managed according to the “Portal Visibility” field in the reference form. Then the records will be displayed respecting the value of the following fields:

 

  • Portal Visibility = Yes
  • Linked Company – if the user company is the same as the linked company of the entity
  • Parent Company – if the user company is the same as the partner company of the entity
  • Owner User – if the user is the owner of the entity

Knowledge Base Visibility

For the visibility of the Knowledge Base in the Deepser user portal, it is possible to act by configuration by going to “SYSTEM > Configuration > Portal – Configurations” and finally Knowledge Base, we will access the Deepser section dedicated to configuring the visibility of the Knowledge Base module on the portal side:

Once the KB module view is enabled and configured, the display of individual records will be managed according to the “Portal Visibility” and “Kb Group View” fields present in the Knowledge Base record configuration:

In addition, it is possible to intervene on the visibility of a single article in the KB always through the “Portal Visibility” field present within the article:

If the “Portal Visibility” field is set to “Yes”, the knowledge base or article will be displayed on the portal side.

Password Visibility

For the visibility of CRM modules in the Deepser user portal, it is possible to act through configuration by going to “SYSTEM > Configuration > Portal – Configurations” and finally Password, we will access the Deepser section dedicated to configuring the visibility of Passwords on the portal side:

From here it will be possible to enable the display of the Password module on the portal side through the “Enable” field.

You can also specify which groups will be able to access these forms or whether all users will be able to access them indiscriminately (by selecting All Groups) via the “Enabled Groups” field.

 

Once the Password module is enabled and configured, the display of individual records will be managed based on the following fields:

 

  • View Groups – if user is part of the group he can only see and not edit the entity
  • View and Edit Groups – if user is part of the group he can see and edit the entity
  • Use Groups – if user is part of the group, he can use the password if provided in other entity like field.
  • View User – if the user is selected, he can only see the entity
  • View and Edit User – if the user is selected, he can see and edit the entity
  • Use User – if the user is selected, he can use the password if provided in other entity like field.
  • Company – if user’s company is selected, he can see the entity

Anyway, an end-user can only save private passwords. So, all passwords saved from end-user portal couldn’t be visible in the backend, but there are available only for him.

Approval Visibility

For the visibility of approvals, in the Deepser user portal it is possible to act by configuration by going to “SYSTEM > Configuration > Portal – Configurations” and finally Approval, we will access the Deepser section dedicated to configuring the visibility of the Approval module:

Inside we will find the “Enable” field as configurable. If enabled, it will allow the use of portal-side approvals.

 

However, a requirement for using portal-side approvals is the use of end-user Empowered licenses.

Only these types of users will have the ability to use the approvals module.

Survey Visibility

For the visibility of Surveys, in the Deepser user portal it is possible to act by configuration by going to “SYSTEM > Configuration > Portal – Configurations” and finally Survey, we will access the Deepser section dedicated to configuring the visibility of the Survey module:

Inside we will find the following configurable fields:

  • Enable: Which allows you to view portal-side survey records.
  • Enabled Groups: If the module is enabled via the “Enable” field, through this field it is possible to enable the visibility of the surveys to selected groups (or to all users by selecting “All Groups”).

The visibility of a single survey on the portal side will be managed based on the enhancement of the “Users” and “Groups” fields present within the survey.

Task Visibility

For the visibility of the Activity module in the Deepser user portal, it is possible to act by configuring it by going to “SYSTEM > Configuration > Portal – Configurations” and finally Tasks, we will access the Deepser section dedicated to configuring the visibility of the Task module on the portal side:

Inside we will find the following configurable fields:

  • Enable: Which allows you to view portal-side task type records.
  • Enabled Groups: If the module is enabled via the “Enable” field, through this field it is possible to enable the visibility of the tasks to the selected groups (or to all users by selecting “All Groups”.

The visibility of the tasks will instead be based on the “Portal Visibility” field present within the task and which must be set to “Yes” to make the portal task visible and the related “Assigned User” and “Assigned Groups” fields to be enhanced according to the users or user to whom the task is to be visible.

Project Visibility

For the visibility of the tasks of the project module, in the Deepser user portal it is possible to act by configuration by going to “SYSTEM > Configuration > Portal – Configurations” and finally Project, we will access the Deepser section dedicated to configuring the visibility of project tasks on the portal side:

Inside we will find the following configurable fields:

  • Enable: Which allows you to view portal-side task type records.
  • Enabled Groups: If the module is enabled via the “Enable” field, through this field it is possible to enable the visibility of the tasks to the selected groups (or to all users by selecting “All Groups”.

 

The visibility of the tasks will instead be based on the “Portal Visibility” field present within the task and which must be set to “Yes” to make the portal task visible and the related “Assigned User” and “Assigned Groups” fields to be enhanced according to the users or user to whom the task is to be visible.

Empowered End User (EEU)

An EEU (Empowered End User) is a licensed user who has access to specific features on the End User Portal, such as:

  • Approval workflows
  • Advanced data visibility.

The license type in this case is different from the license for backend users of Deepser, as it can only be used for End Users who therefore have access solely to the customer portal.

You can check the available and active licenses directly from the main users’ screen in the Backend (System > Permissions > Users):

Setting an end user as empowered, can be done by setting to “Yes” the “Empowered” field on the User model formtemplate. The “Empowered” field is visible for User model with role of “End User“.

NOTE: You can set it to “Yes” only if you have the EEU license type available. Additionally, it can only be set for users with the “Users” (End User) role.

EEU – Approvals

The Empowered End User can approve or refuse an approval process. As an EEU all the approvals will be visible through the user menu in the End Users portal.

After clicking “My Approvals” EEU will be able to see the approvals grid assigned to them.

You can find more details on how to use the Approval flow by referring to the dedicated article here.

EEU – Access Users and Groups

When a user is configured as ‘Empowered,’ they gain expanded visibility access for operations and other models, in addition to the approval flow. This is achieved through the Access Users and Groups fields, which are available by default in the Operation model and allow for more granular control over user permissions and data visibility.

  • Access User: By using this field in an operation, you can grant each individual EEU access to specific entities, such as operations. Once access is granted, the EEU will be able to view the ticket through the end-user portal.
  • Access Group: Like the Access User field, when populated within an operation, it allows you to extend the visibility of an entity if the user who is part of the group is of the “Empowered” type.

    You can find more details on how to use the Access User and Access Groups fields by referring to the dedicated article.

Company Supervisors

Company supervisors are end users who have visibility on all tickets of their company, thus bypassing the limitation of visibility regarding only the tickets requested by them.

Users can be created as Company Supervisors from the beginning, or they can be promoted later.

Below we will explain the procedure for promoting a user to a Company supervisor, to create a user from the beginning please refer to the guide regarding the creation of a user.

PROMOTE A USER TO COMPANY SUPERVISOR

To promote a user to a company supervisor, you will need to go to the System -> Permissions -> Users menu

From here, it will now be possible to access the users’ editing by clicking on an existing user.

In the screen that will open select “Is Supervisor” and set the value from “No”

to “Company Supervisor”

At this point, click on the “Apply” button or on the “Save” button

Finally, the modified user will be a Company Supervisor.

Additional Companies

Additional Companies are companies with which a user can be associated in addition to his principal company, to have visibility also on the tickets generated by these additional companies and to open tickets on behalf of third parties, in the event that he is a company supervisor.

If the user is not a company supervisor, he will be limited to seeing only the tickets assigned to him, but in the form templates where the company field is present, he can select either his company or one of the Additional  Companies.

ADDING AN ADDITIONAL COMPANY TO A USER

To add an Additional Company to a user you will need to go to the System  ->  Permissions  -> Users menu.

At this point it will be necessary to click on the user we are interested in editing.

Once we have entered the modification of the user to whom we are interested in adding the additional company, we identify the “Additional Companies” field in the template form.

 

At this point, we click on the field and start writing the name of the company to filter the field.

In this case, the company will be “Acme International”

Once you have identified the desired company, simply click on it to confirm.

The result will be as follows:

Now you will need to click the “Apply” button or the “Save” button to confirm the changes.

At this point, the changes will be applied correctly to the user.

Access Groups

You can also extend ticket visibility by using the “Access Groups” field for portal end users.

To use this field, it will be necessary to include it in the operations form as it is not normally displayed:

The field in question, in fact, through the multiple insertion of 1 or more groups, allows a ticket to be displayed even to groups of users who normally do not have visibility.

On the portal side, the standard display of information is based on the “Requester” field or on the company to which they belong in the case of supervisor users. This field gives you the option to extend the view.

However, to use this feature you must comply with the following rules:

  1. If you want to give the visibility of a ticket on the portal side to an end user, the latter must have an “Empowered End User” license and therefore must have the “Empowered” flag within his user database.
  2. For a ticket to be visible on the portal side, the user group must have visibility of the type of service linked to the ticket (via the “Portal User Groups” field in the configuration of service types).

Access Users

You can also extend ticket visibility by using the “Access Users” field for portal end users.

To use this field, it will be necessary to include it in the operations form as it is not normally displayed:

The field in question, in fact, through the multiple entries of 1 or more users, allows you to display a ticket even to users who normally do not have visibility.

On the portal side, the standard display of information is based on the “Requester” field or on the company to which they belong in the case of supervisor users. This field gives you the option to extend the view.

However, to use this feature you must comply with the following rules:

  1. If you want to give the visibility of a ticket on the portal side to an end user, the latter must have an “Empowered End User” license and therefore must have the “Empowered” flag within his user database.
  2. For a ticket to be visible on the portal side, the user must be part of a group that has visibility of the type of service linked to the ticket (via the “Portal User Groups” field in the configuration of the types of service).

Resources

In Deepser the resources are basically the modules or service that Deepser makes available.

An example of the exposed resources is shown below.

The visibility of  the resources in Deepser can be set up to the model level.

The user will only be able to see modules and resources that have been set as visible to the membership role.

Activity, Worklogs & Comments


This Course covers everything related to Deepser Activities, which is a comprensive term for Comments and Worklogs. You will learn everything related to Activities usage and advanced System Configuration.

Articles

  • DeepActivity Comments
  • Placing a comment
  • Comments System Configuration
  • DeepActivity Worklog
  • Entering a Worklog
  • Enabling Worklogs in the User Portal
  • Worklog Global Grid
  • Worklog Global Grid Configuration
  • Activity Global Grid Advanced Configuration

DeepActivity Comments

With the term Activity, Deepser refers to some activities that can be done on tickets.

There are two types of activity, Comments and Work Activities, both of which are available, if configured, either in the Backend or in the Users portal.

Activities are a great way to track relevant information and communication regarding a ticket. They facilitate ticket resolution by providing an additional point of contact between operators and end users.

Comments are used in ticketing to connect users and groups related to the ticket itself. Through comments it is possible to communicate updates, useful information to close the ticket, or put in contact end users with operators.

Placing a comment

This guide will explain how to place a comment on an Operation.

1 – It is possible to access the “Activities” section of Operations through the User Portal or Backend, if properly configured.

1a – Through the User Portal, simply select the Operation on which you want to add a comment from the right grid.

1b -Through the Backend it is necessary to open the Service module through the drop-down menu, and click All to visualize all the Operations. Finally open the Operation on which you want to add a comment.

2 – At this point, scroll down to the Activity section, here comments and Work Activity are visible, the Comments tab will already be highlighted by default.

 

2 – To add a comment, click on Add Comment

3 – The form for inserting a comment is shown below

The meaning of the fields is the following:

CampMeaning
Visible on PortalSpecifies whether the comment should be visible in the user portal, thus to end users.
Created ByIndicates the creator of the comment, it is automatically filled with the current user who is commenting.
DescriptionThe text of the comment, formatted with images and structures such as tables, etc.
Comment AttachmentsAllows to attach files to the comment. Note: The files will not appear as ticket attachments, but only to the comment.

4 – To save the comment, simply click on the green checkmark in the upper right corner.

5 – The comment will then be displayed under the ticket

Comments System Configuration

For comments, it is possible to make advanced system configurations, to set options such as: in which temporal order to display comments, and to automate the change of status of an Operation when a comment is inserted.

These configurations are available in Deepser’s system configuration menu. To access in system configuration, you need to use Deepser’s backend dropdown menu, then System->Configuration->Activity->Configurations.

This is the section dedicated to the configuration of comments at system level

The meaning of the fields is the following:

SectionCampMeaning
Order CommentsComment order direction (creation date Asc/Desc)Allows you to sort comments from least to most recent (Asc), or from most recent to least recent (Desc).
Changes Service Operations status when adding a CommentEnabledIf set to yes, when a comment is added to a Service Operation, it will automatically change state if it meets some rules defined by the fields below.
 Select New Status Indicates the state in which the commented Operation is to change. For example, Taken over.
 Exclude Status Operations in any state shown in this list will not be affected by this automatism. For example, if you only want to change Operations to New status, enter all other statuses in this field.
 Apply if Created By user is in Group Allows to enable this automatism only to users member of some groups.
For example, if the status change has to occur only when an operator enters a comment, select a group of Operators.
Save Config Allows you to save the current configuration.

DeepActivity Worklog

With the term Activity, Deepser refers to some activities that can be done on tickets.

There are two types of activity, Comments and WorkLogs, both of which are available, if configured, either in the Backend or in the Users portal.

Activities are a great way to track relevant information and communication regarding a ticket. They facilitate ticket resolution by providing an additional point of contact between operators and end users.

WORKLOGS

WorkLogs are a useful tool for tracking each individual activity performed to bring the ticket to closure. WorkLogs can also be used in reporting to provide a cumulative calculation of the total work hours per user, performed on a ticket.

Entering a Worklog

This guide will explain how to create a WorkLog for an Operation.

1 – It is possible to access the “Activities” section of Operations through the User Portal or Backend, if properly configured.

1a – Through the User Portal, simply select the Operation on which you want to add a comment, from the right grid.

1b – Through the Backend it is necessary to open the Service module through the drop-down menu, and select All to visualize all the Operations. Finally open the Operation on which you want to add a WorkLog.

2 – At this point, scroll down to the Activity section, where comments and Work Activities are visible, and select the WorkLog tab.

2 – To add a WorkLog, click on Add Activity.

3 – The form for inserting a WorkLog is shown below

The meaning of the fields is as follows:

FieldsMeaning
Started AtIndicates the day and time when this activity began
StatusIndicates the status of the Activity
DurationIndicates the duration in hours and minutes of the activity , this parameter can be used in reporting to calculate the total working hours.
DescriptionThe text with the description of the work activity, formatted with images and structures such as tables, etc.
Created ByIndicates the creator of the activity , it is automatically filled with the current user who is entering it.

4 – To save the work activity, simply click on the green checkmark in the upper right corner.

5 – The result is as follows

Enabling Worklogs in the User Portal

To display WorkLogs  in the User Portal, so that end users also have access to them, you need to make some system configurations.

These configurations are available in Deepser’s system configuration menu.

To access system configuration, you need to use Deepser’s backend dropdown menu, then System->Configuration->Portal->Configurations.

This is the section dedicated to the system configuration of WorkLogs 

The meaning of the fields is the following:

CampMeaning
Show WorklogMakes worklogs visible in the user portal. The worklogs will be read-only, if ‘Add/Edit Worklog’ is set to No.
Add/Edit WorklogGives End Users the ability to insert worklogs, or modify those already present in tickets.
Save ConfigAllows to save the configuration

Worklog Global Grid

The global grid of work activities is a configurable grid that allows you to view all work activities. This can only be reached from the backend.

You can go to the grid from anywhere in Deepser in the following way:

At the top right you can find the 3 dots: by clicking on them you will see the Task item and the Work Activity item.

By clicking WorkLog then we will access the grid that if not configured will show the following fields:

FIELDNOTES
ActionThrough a floating window, the entity in which the related work activity is contained is opened (for example, the ticket in which the activity is contained). Clicking inside the row instead opens in a floating window the work activity.
ModelA template that contains the activity of work (usually contained in operations, i.e., tickets)
Model IdThe id of the template in which the activity is contained. If the work activity is in a ticket, the Id of that ticket will be shown.
Visible to FrontendVisibility of activity in the front-end. By default, work tasks are never shown in the user portal.
Started AtThe date and time that indicates the start of the activity.
Ended AtThe date and time that indicates the end of the task.
DurationDuration of the activity.
Created ByThe user who created the task.
Created AtThe date and time that indicates the creation of the work task.
Updated AtThe date and time that indicates the last change in the work task.

Worklog Global Grid Configuration

EDIT GRID FIELDS

You can access the global grid configuration for work tasks through the edit button below.

Inside we could choose which fields to display and which not:

  • the available columns column lists all fields that are not shown in the grid
  • In the Visible Columns column, all the fields that are currently shown in the grid will be listed and we could choose in what order they will be shown in the grid.

To insert or remove fields from the grid, you can simply use the arrows at the ends of the fields.

To change the order of the fields shown you can use the Drag & Drop, then simply drag the fields.

By then clicking on one of the displayed fields, it is possible to define whether it is possible to make the field sortable, filterable and / or multifilterable in the case of a select field through the relative checkboxes.

 

COLLECTION OF ACTIVITIES DISPLAYED IN GRIDS

Within the grid in which we are located it is possible to define the collection of work activities that must be retrieved and shown in the grid through the appropriate Query Builder.

For example, you can view only the activities that have been placed within the tickets by setting the following control in the Query Builder: Model equal DeepService – Operation.

 

MASS ACTION AND EXPORTS

Through the Massive Actions checkbox, you can activate the massive actions in the grid.

Massive actions allow you to modify one or more work activities through a grid selection. The massive action that is currently implemented by default is that of elimination.

NB: Elimination through massive action will result in a physical deletion to databases. Deleted work tasks can no longer be recovered.

Through the Enable Export checkbox, on the other hand, it is possible to enable the export of the data displayed in the grid in XLSX or CSV format.

Once the export is enabled, a field will be shown in the grid that allows you to choose the format in which you want to extract the work activities and a button to export them.

Through the export will be extracted in the desired format the data of the work activities that are shown in the grid.

At the click of the sexport, you will be shown a popup that will ask if you want to export the only work activities visible at the time of export or if you want to export all the work activities.

Activity Global Grid Advanced Configuration

VIEW THE TITLE OF THE ENTITY TO WHICH THE WORK TASK IS ASSOCIATED

Some fields already present in the Work Activities may contain useful and convenient information to be displayed in the grid, in which, however, a brief configuration is required to make them actually usable.

In fact, we can see that if we want to view the contract or the contract line to which a work activity has been associated and we make the fields already available visible in the grid, some numbers will be displayed which will represent the ID of the relative entities.

To be able, for example, to view the name of the contract associated with a work activity, it is necessary first to go to the modification of the grid and make the Contract column visible.

It will then be necessary to click on the field just made visible and make a change on the type by setting it from Text to Options.

By pressing the </> key you can define custom PHP code for each column and change the printed value (Renderer) or change the options of a Field of type Options (Options).

In the Options field you will then need to enter the following custom code:

				
					// retreive of the Contract collection
$contractCollection = Deep::getResourceModel('deep_contract/contract_collection');
// convert the collection into an associative array
// the key is the Contract Id and the value the Contract Name
$optionsArray = $contractCollection->toOptionHash();
return $optionsArray;
				
			

Similarly, to view the name of the contract line associated with a work activity it is necessary to make the Contract Line field visible, change its type in Options and within the Options field to define custom code insert the following code.

				
					// retreive of the Contract Line collection
$lineCollection = Deep::getResourceModel('deep_contract/line_collection');
// convert the collection into an associative array
// the key is the Contract Line Id and the value the Contract Line Name
$optionsArray = $lineCollection->toOptionHash();
return $optionsArray;
				
			

At this point we may display the names of Contracts and Lines of Contracts that have been associated with the related work activities. We can also make these fields multifilterable and sortable.

MASS ACTION CONFIGURATION

It can often be helpful to set the same value to multiple tasks. In these cases, the use of mass actions is effective.

At the moment, the only massive action already prepared by the system in the grid of work activities is that for the (physical) elimination of one or more activities.

You can still configure a custom massive action by accessing the grid change. Below the Mass Action checkbox is the </> button that allows the opening of the custom PHP script area.

The following example shows the custom code that implements a massive custom action to enable or disable the visibility in the portal of one or more work activities.

The code must be inserted directly into the custom PHP script area.

				
					// create the array for the option visibility
$visibilityArray = [0 => 'No', 1 => 'Yes'];
 
// initialize html component
$this->addMassActionItem('visibility', [
    'label' => 'Visible to Frontend',
    'additional' => array(
        'visibility' => array(
            'name'   => 'visibility',
            'type'   => 'select',
            'class'  => 'required-entry',
            'label'  => 'Visible to Frontend',
            'disable_js_select' => true,
            'values' => $visibilityArray,
        )
    ),
    //callback is the method that contains the logic of the action
    'callback' => function() {
        /** @var Deep_Grid_Model_Grid_Massaction_Callback $this */
        /** @var Mage_Core_Model_Resource_Db_Collection_Abstract $collection */
        $collection = $this->getGrid()->getModelInstance()->getCollection();
         
        //$this->getIds() returns the id of the selected activities
        $collection->addFieldToFilter('entity_id', ['in' => $this->getIds()]);
         
        // $collection contains the instances of the selected activities and we iterate on them
        foreach($collection as $activity){
            //$this->getValue() contains the id of the new option visibility, the selected one
            //set the new activity visibility
            $activity->setPortalVisibility($this->getValue());
            //save the activity
            $activity->save();
        }
    }
]);
				
			

By inserting this script, it will then be possible to select one or more work activities and decide whether or not to make them visible in the end user portal.

Roles

In Deepser, roles are used to define which resources the user will have access to.

We can exemplify the concept roles manage Vertical visibility in Deepser, that is, the visibility of the modules presents in the sidebar

THE MAIN ROLES IN DEEPSER AND THE PREDEFINED ROLES

The default roles in Deepser are:

RoleDescription
AdmininstratorAdministrators Users in Deepser, are users that have global access and bypass the limits of visibility in the backend, in addition to them have faculty to modify the grids and form templates. This is the only role that has access to the system configurations and the System tab.
Super AdminSuper Admins are users with Administrator role who have set “All” in the resource visibility section. This role is the only one that has access to scripting areas.
AgentsThese Users have the right to modify the grids and form templates, but they do not have access to the scripting areas or even to the modules placed in the System tab. For the rest by default, they have global access to all other modules.
Key UsersThese users are comparable to Agents users, but unlike the latter they have no ability to modify any system configuration, including grids and form templates.
UsersThese are the end users, as a rule, these users do not have access to the backend but only to the end user portal. Since they do not have access to the backend, they cannot change any system configuration or even see the tickets that have not been opened by them. If there is a need for an end user to see tickets not opened by himself, he can be modified by setting him as a Company Supervisor, in this case the user will be able to see all the tickets created by his company. Alternatively, you can configure the user as empowered user, this will give him visibility even on tickets not belonging to his company.
 

Board

In Deepser there is a “Board” module.

The Board module allows you to create custom Boards in Kanban Format.

Kanban is a framework for Agile development that allows you to visualize your workflow, focus on progress, and optimize efficiency.

Deepser Boards can be of 2 types: FreeForm or Live.

In this course we will analyze everything related to Deepser boards.

Articles

  • Enable groups to create boards
  • Creating a FreeForm Board
  • Creating and customizing a Lane
  • Entry Creation
  • Board Live
  • Live Board Creation
  • Advanced Live Board Configuration
  • Creating and customizing a Lane
  • Creation and Advanced Configuration of a Lane and Drop Code

Enable groups to create boards

To enable the groups to see the boards it will be necessary to go to the menu: System -> Configuration

At this point you need to go to the Tab Board -> Configuration

From the “policy” tab it will be possible to configure which groups will have the possibility to create boards  and board  freeform.

Creating a FreeForm Board

In Deepser to create a new board of type FreeForm You will need to go to the menu: Board -> List.

To create a new board once you go to the Board -> List menu you will have to click on the “+” button at the top left corner:

On the page that opens set the type to “FreeForm”.

At this point you can configure the name field with the desired name and the Description field with the description that will be displayed in the new board.

At this point you can check that the status of the board is set to “Enabled”  and click on the “Save” button to create the board.

At this point the new board will have been created.

Access a Board

To access a board you will need to go to the menu: Board -> List

At this point locate the board you want to view and click on the “View” button

Customize a board

To customize a board you will need to go to the menu: Board ->List, go to the three dots.

At this point it will be possible to add an icon by clicking the choose file button (3) or select a background for the board through the “background” or “background” selector (4), then click the “save” button (5).

For the logo it will now be present in the custom board.

To view the background you will need to go inside the board that you are customizing.

Share a Board

Deepser allows you to share a board in reading or reading and editing or reading, editing and interaction to allow you to make boards a very effective and immediate collaborative tool, suitable for the management of complex processes.

To share a board you will have to go to the menu: Board -> List.

From here you will need to click on the three dots placed on the board you want to share:

At this point the following screen will open:

The sharing fields are expressed in the following table.

FieldDescription
View UsersUsers who can view the board read-only
View GroupsGroups that can view the board as read-only
View and Interact UsersUsers who can view and move board items, but not edit or delete them
View and Interact GroupsGroups that can view and move board items, but not edit or delete them
View, Interact and Edit UsersUsers who can edit the board, move the Entries and delete them
View, Interact and Edit GroupsGroups that can edit the board, move the Entries and delete them

Note: In order to share a board it will be necessary that the user is registered with the system. In addition, in order for the user to view and interact with the board it will be necessary that he is a backend-enabled user and that he has a role where it is allowed to view the boards among the options in the side menu of Deepser.

Creating and customizing a Lane

A lane in Deepser is the entity within the boards that serves to contain and organize tasks in a logical way.

To create a Lane in Deepser you will need to go to the board where you want to add the wool, here you will have to click on the “+” button at the top right corner.

In the screen that opens you can set the name, filling in the “Label” field (2) and then click on the “Save” button (3).

Now the system will create the new Lane with the specified name.

Customizing a Lane

 To customize a Lane you will need to go to the Lane to customize and click the 3 points .

Here you can change the name or color of the Lane.

To change the name, simply edit the contents of the label field.

To change the color you will have to click on the color picker (2)

choose the desired color and click “save ” (3) and then the “Apply” button(4).

Finally, the Lane will be colored in the desired color.

 

Entry Creation

To create a new entry in the boards you will need to go to the section: Board -> List:

Then you will have to go to the board where you want to insert the Entry, in our example “Board Name”

Here, click on the “View” button

Once you enter the board you will need to identify the lane where you want to add the Entry

After that it will be necessary to click the “+” button in corrispondence of the Lane in which you want to add the Entry

At this point you will have to give a title tothe new  Entry and then click the tick button  

At this point it will be possible to see the new entry in the lane.

Move an entry between different lanes

To move an Entry to another Lane simply click on it and drag it to the new lane.

Once the Entry is released, the result will be as follows:

Board Live

The Live boards in deepser are a particular type of board, that instead of the entries allows to organize at logical level the entities inside Deepser.
In this lesson we will analyze how to create, customize and manage Deepser’s Live boards.

Live Board Creation

In Deepser it is possible to create in addition to freeform boards also live boards.

Live boards allow you to manage Deepser entities in graphical mode by representing the individual entity as an Entity of a board.

To create a live board you will need to go to the menu: Board -> List

Here you will need to click on the “+” button:

At this point the board creation screen will appear.

Here we are going to select as board type “Live” and as Model Alias “Deep service Operation”.

Similarly to the freeform boards also in the live board will be possible to insert an icon, to do so it will be sufficient to click on the button

Next we click the apply button to save the changes

At this point the live board will be created by Deepser.

The end result is as follows:

Now the board is configured for basic usage.

By default is configured to retrieve a collection of all Service  Operations. We will see in the next topic how to limit the number of  Operations or in  general entities of Deepser that can be recovered by applying filters to the collections of datas.

Collection Board Live Configuration

To configure the collection of a live board you will have to go to Board -> List

At this point you will have to go to the live board you want to edit and click on the three dots to access the configuration screen.

At this point you will have to go to the “Prepared Collection” section

Here it will be possible to configure which tickets will be viewable within the board.

For example, suppose you want to display only tickets in a new state or work in progress.

To do this, simply configure the query builder like this:

To finalize the changes you will need to click on the Apply button

Advanced Live Board Configuration

In this article we are going to deal with two examples of configuration of advanced live boards.

EXAMPLE 1

In this example we are going to replicate the configuration of the data collection of the previous board but using the scripting area present in the board.

To create a live board you will need to go to the menu: Board -> List

Here you will need to click on the “+” button:

At this point, the board creation screen will appear.

Here we are going to select as board type “Live” and as Model Alias “Deep service Operation”.

Similarly to the freeform boards also in live Boards it will be possible to insert an icon, to do so it will be sufficient to click on the button

Next we click the apply button to save the changes

Now we have to go to the scripting area, like the one shown in the figure:

In the scripting area that will open we are going to insert the following code:

				
					/* Only select tickets in New and Work in progress statuses**/
$this->getModelCollection() ->addFieldToFilters('status',["in"=>[1,2]]);
				
			

At this point we must go to click the save button to confirm the configuration.

EXAMPLE 2

In this example We are going to configure a live board that will load all the tickets for which the company of the requesting user has a flag set for priority assistance.

For this example we will assume that there is a “cust_prioritary_assistance” field in the company, of the checkbox type.

When the checkbox is flexed we will consider the company as a company with priority assistance.

To create a live board you will need to go to the menu: Board -> List

Here you will need to click on the “+” button:

At this point, the board creation screen will appear.

Here we are going to select as board type “Live” and as Model Alias “Deep service Operation”.

Similarly to the freeform boards also in live boards it will be possible to insert an icon, to do so it will be sufficient to click on the button

 At this point we can go to add in the scripting section of the board the following code:

				
					$this->getModelCollection()->getSelect()->joinLeft('deep_company_company','main_table.requester_company_id = deep_company_company.entity_id',[]);
$this->getModelCollection()->addFieldToFilter('deep_company_company.cust_prioritary_assistance', 1);
				
			

Now we must click on the Save button to save the board.

Creating and customizing a Lane

A Lane in Deepser is the entity within the boards that serves to contain and organize in a logical way the entities loaded by the board.

To create a Lane in Deepser you will need to go to the board where you want to add the wool, here you will have to click on the “+” button at the top right corner.

In the screen that will open you can set the name, filling in the “Label” field.

At this point you can enter a new field in the Field field to display. In this case we enter the field “entity_id”of the ticket. By clicking on the button

At this point we select in the Field field the value “entity_id” and in the label field “Yes”.

At this point you will need to click on the apply button.

Now the system will create the new Lane with the specified name.

CUSTOMIZING A LANE

The following properties of a lane can be customized: the name,  the color of the Lane, the data collection, the Drop Code or the fields to be displayed for each ticket in that Lane.

CHANGE THE NAME OF THE LANE

To change the name, simply edit the contents of the label field.

Next you will need to click on Apply:

CHANGING THE COLOR OF A LANE

To change the color of the Lane you will need to go to the Lane to customize and click the 3 points.

Here you can select the color to assign to the Lane using the color picker:

choose the desired color and click “Save”:

and then the “Apply” button:

Finally, the Lane will be colored in the desired color.

PREPARED COLLECTION CUSTOMIZATION

In Deepser’s live boards Lanes  the prepared collection section is used to define which tickets will be displayed in the Lane.

To customize the prepared collection of a Lane in a live board you will need to go to the Lane to customize and click the 3 points.

Now it will be possible to set the data collection to be displayed in that lane through the “Prepared Collection” section

Let’s say you want to display in this Lane only the entities in a state new, you can do it through the query builder:

At this point click on the “Apply” button:

Now the lane will be updated automatically by the system loading only the tickets that correspond to the filters set

CUSTOMIZE THE DROP CODE

The drop code in Live boards is the code that is executed when a ticket is dragged onto the board.

To customize the drop code of a Lane in a live board you will need to go to the Lane to customize and click the 3 points.

Here you will be able to set the code to run in the “Drop Code” section via the query builder.

In the current example, let’s say we want to set that when a ticket is dragged into this section it takes on a new state:

At this point when a ticket is dragged on this board, its status will change to new.

Creation and Advanced Configuration of a Lane and Drop Code

A Lane in Deepser is the entity within the boards that serves to contain and organize in a logical way the entities loaded by the board.

In this article we will see an example of advanced lane configuration using the scripting area on the lane and an advanced example of changing the Drop Code of a lane.

EXAMPLE 1

In this example we are going to show in the lane only the tickets in The New state, by default id 1.

To Edit a live lane you will need to go to the board where you want to change the wool, here you will have to click on the three dots:

At this point we will have to go to the scripting area “Data Collection (Script)” as in the figure shown here:

Here we are going to enter the following code:

				
					/**Visualizing only the ticket in with state "NEW"**/
$this->getModelCollection()->addFieldToFilter('status',["eq"=>1]);
				
			

At this point click on the “Apply” button:

Now the lane will be updated automatically by the system loading only the tickets that correspond to the filters set

Customize the Drop Code

The drop code in Live boards is the code that is executed when a ticket is dragged onto the board.

To customize the drop code of a Lane in a live board you will need to go to the Lane to customize and click the 3 points.

In the current example, let’s say we want to set the company as a company with priority assistance when a ticket is dragged into this Lane.

To do this we insert in the scripting area “Drop Code (Script)”:

the following code:

				
					/**Setting prioritary assistance for the company of the dropped ticket **/
$company = $this->getDroppedModel()->getRequesterCompany();
$company->setData('cust_prioritary_assistance',1)->save();
				
			

At this point click on the “Apply” button:

At this point when a ticket is dragged on this board its status will change again.

Creating and Managing Roles in Deepser

In deepser, roles are an important component in visibility management.

The roles allow you to manage the visibility of the modules accessible to user accounts (e.g. password, crm etc) or even which users can access the Deepser backend and which can only access the user portal.

Creating a Role

To create a role in Deepser you will have to go to the “System the Permissions->Roles”  menu.

At this point in the screen that will open you will have to click on the “Add New Role”

On the next screen you can set the “Role Name” field which will define the name that will have the new role.

In the type field it will be possible to define the Type that will have this role by compiling the “Type” field.

Then moving to the “Roles Resources” tab you can define which resources will be visible to the user to whom this role will be assigned by configuring the “Resource Access” field to Custom an selecting the resources you want to expose to this role.

Note: if you want to set the role to have no visibility limitations you can opt to select from the drop-down menu the item “ALL” instead of the item “Custom”, in this way no visibility limitations will be applied on the role (however this will not affect the visibility configured for groups).

Now click on the  “Apply” or on the  “Save” button.

Once the role has been created, a third item will appear in the list of tabs: Role Users.

Using this tab you can get a quick overview of all the users who have been assigned that role.

Categories

Categories in Deepser are an important tool for the management of Tickets, CIs, or the Deepser entities in general  by backend side operators.

The Categories allow you to describe quickly and concisely the scope of that specification required, for greater flexibility Deepser allows you to organize the categories on a hierarchical scale of up to three levels which translates into being able to have a first level category with N categories of second level and each of them with N categories of third level.

Articles

  • Category Overview
  • Category Configuration
  • Category Usage

Category Overview

Categories in Deepser are an important tool for the management of Tickets, CIs, or the Deepser entities in general  by backend side operators.

The Categories allow you to describe quickly and concisely the scope of that specification required, for greater flexibility Deepser allows you to organize the categories on a hierarchical scale of up to three levels which translates into being able to have a first level category with N categories of second level and each of them with N categories of third level.

The categories in addition can be visible on one or more types of service or some categories can be visible only by some groups of users, this allows you to manage in a granular way the categorization of tickets, in addition they can be enabled and therefore visible or be disabled and therefore not displayed within the appropriate field.

In addition, they can be used as parameters in routing rules (Automatic assignment of tickets, these will be covered in a later lesson) to assign a ticket to a user or group based on the category.

Category Hierarchy

Categories in Deepser are organized in a hierarchical tree structure of up to 3 levels.

So each first level category corresponds to zero or more second-level categories, and for each 2-level category zero or more third-level categories correspond.

This structure is called hierarchical because if you apply visibility restrictions on a higher-level category, the lower-level categories will inherit those limitations.

Categories in addition can be made visible for all models, by default, or only for a specific model.

Category Configuration

Creating New Category In Deepser

To create a new category in Deepser you will need to go to the menu: System -> Categories

At this point, you will need to click on the “Add Root Category” button

At this point, the following screen will open:

Below are the fields with their meanings:

FieldDescription
NameThis field is the name that the new category will have.
DescriptionThis field is the description that will be associated with the new category
ImageThis is the icon that will be displayed side by side next to the category name (only if this field is filled in)
StatusThis field is the status that will have the new category: if the status will be enabled then the category will be displayed among the usable and selectable categories, otherwise it will not be displayed among the categories.
Frontend VisibilityThis field indicates whether this category will be viewable among the categories in the guest portal (only if the guest portal is enabled)

Once you have filled in the fields, you can click on the “Save Category” button

Creating New Sub-Category in Deepser

To create a new subcategory in Deepser you will need to go to the menu: System -> Categories

At this point, you will need to select the category that will become the parent of the new subcategory and click on the “Add child Category” button

Now the following screen will open:

Below are the fields with their meanings:

FieldDescription
NameThis field is the name that the new subcategory will have.
DescriptionThis field is the description that will be associated with the new subcategory
ImageThis is the icon that will be displayed side by side next to the subcategory name (only if this field is filled in)
StatusThis field is the status that the new subcategory will have: if the status will be enabled then the category will be displayed among the usable and selectable subcategories, otherwise it will not be displayed among the subcategories.
Frontend VisibilityThis field indicates whether this category will be viewable among the subcategories in the guest portal (only if the guest portal is enabled)

Once the fields have been filled in, it will be possible to click on the “Save Category” button.

Category Visibility Management

Model Visibility

On model visibility tab you can limit the usage and access of a category on a model. For example, you can set a category to be visible only on operation model.

To configure a new model visibility, just click on the ‘+’ button inside model visibility tab.

Model Visibility – Example

Below there is an example of a model visibility, that limits the ‘User Equipment’ category to only operations of type ‘Request’ and ‘Incident’. When users open a ticket of type ‘request’ or ‘incident’, they will be able to view and use the ‘User Equipment’ category.

Field

Description

Model

Select field where you can choose the model which will have visibility to this category.

Portal Visibility

With this field you can make the category visible or not on End Users portal.

Frontend Visibility

Select field with Yes/No values , that can set the category visible on frontend portal.

Expression

Query Builder field that adds another layer of visibility on the category. With this field you could limit the visibility of a category if certain conditions based on model’s fields, are met.

Expression (Script)

Scripting field that has the same functionality as the query builder, but here you can write the conditions directly by code.

Group visibility

By configuring group visibility you can limit, users access to a category based on the group that they participate.

To set group visibility, just go under group visibility tab and select the groups of visibility on the ‘Enabled Groups’ field. In the example below, the “User Equipment” category is visible only for users that are part of “IT- First Level” or “IT Customers” groups.

Guest Portal Visibility

To make a category visible in the guest portal, you need to go to the menu: System  -> Categories.

Here, you will need to click on the category we want to change.

At this point, we must change the field “Portal Visibility” to “Yes”

Finally, we must click on the “Save Category” button.

Category Usage

Categories in Modules

The usage of categories is available by default in Operation or CMDB models, through a custom field with element type ‘category’.

  • Category field configuration

This is how to category field shows on the formtemplate after configured.

On the first select field there are shown all the Categories of level 1. After a first category is chosen the select of second categories is shown and so on.

Categories in Grids

Categories of different levels can be used on grids of the models that have the category field configured. To be able to display the categories fields in grids, fields should be dropped on the visible columns of grid. The column type should be ‘options’ , so that the category name is displayed and not its entity id.

After adding the categories this is how they will appear on the grid.

Creating a new user

A user in Deepser is an individual who interacts with the system, utilizing its features and functionalities.

To create a new user in Deepser you will need to go to the menu System  ->  Permissions  -> Users(1)

In the screen that will open, you will need to click on the “Add User” button(2)

At this point, the following screen will open:

FieldDescription
AvatarProfile picture of the user.
UsernameUsername of the user, this will serve to log in, this is a mandatory field to create and in addition this field must be unique within Deepser.
FirstnameThe name of the user. This is a required field
LastnameUser’s lastname.
EmailUser’s email
PasswordPassword of the user, note that this field is always white because the user’s password is not stored in a database format that is invertible, consequently the field remains unvalued by default even if the user has a password set, except when changing the password itself. In case of changes to this field when saving the user Deepser will automatically update the value of the password present in db.
Password ConfirmationConfirm the user’s password, like the previous field, this is also not valued except when changing the password itself.
RoleThe role of the user, depending on the role the user will have different visibilities on the various parts of the product. For example the Users role, who by default sees only the End User Portal. The roles of the users will be deepened in the dedicated Lesson, click here to go to the corresponding lesson.
ActiveIndicates whether the user is authorized to access Deepser. If the value is “Active” the user will be enabled to access, if the value is “Inactive” then the user will not be authorized to access Deepser.
Startup PageThis field indicates which is the default page to which the user will be redirected after logging in.
LocalIndicates the language in which the user visualizes Deepser interface
TimezoneIt indicates the time zone associated with that user, it is important to indicate the correct time zone so that Deepser can correctly set the format of the dates in notifications and date fields.
CompanyThe company field indicates which company the user belongs to, this field is very important since Deepser companies are one of the key elements in visibility management. The companies will be analyzed in the following lessons, click here to go to the lesson on the companies.
Additional CompaniesAdditional companies indicate to the data of which other companies the user will have access. This topic will be deepened in the lesson on company, this field will be selectable only after the user has been saved at least once
Is SupervisorThis field indicates whether the user will be a company supervisor. A company supervisor will have the ability to view and modify the tickets created by the users of his company
Company VisibilityThis field indicates if the user will have limited visibility to Company Data
Portal CMDB VisibilityThis field indicates if the user will see the cmdb in the user portal.
OTL TokenThis token if passed as a parameter (token) in the url of the request (query string) allows you to access Deepser without logging in. Note that the setting of direct access by token is by default disabled for security reasons, in addition for security reasons this token has validity of only one use, after which it is automatically reset by the system, this is done to avoid data theft.  
rp_tokenThis token is used to reset a user’s login credentials. This is a system field, at the operational level there is no use for this field.
LDAP SSO Identifier Field ValueA system field used to map the correspondence between users from AD and those from sso
API TokenThis is the “Barer Token” for access to Deepser’s A.P.I. (Application Programming Interface) To go to the course Deepser’s A.P.I. click here
EmpoweredIndicates if the user is an Empowered user, Empowered users are end users who are not limited to seeing only tickets for which they are requesters or whose company is the requesting company.

Once you have filled in the fields, you will need to click on the “Apply” or “Save” button.

Add the user directly in a group

After you have created the user you can add it directly in a group by going into the ‘’Groups’’ tab(1) and clicking Add(2).

In the following screen that will open, you will have to check the group(s) that you want the user to be added to(1) and select the action add and then submit it(2).

Then you simply have to close the window and the groups the user is included in will be shown in the “Groups” Tab.

Creating a user from an operation

Another way to create a user is directly from an operation(ticket). To do so go to the Service(1) Module and afterwards go inside a ticket.

To create a new user you have to click on the user+ icon at the Requester fieled(2) and a window will pop up. All you have left to do is fill out the necessary fields explained at the table above.

Another case is when the ticket is created with an email, without a user, like this.

All you have to do is click on the user+ icon at the Requester Field and at the window that will pop up, the email field would be automatically filled for you, so you have to complete the rest of the fields.

Note: On user creation, the default role will always be “Users” (in “Role” field), which identifies an end user. Remember to change the role according to your needs. You can check available roles here.

Create a user from CRM Contacts

To create a user from the CRM Contacts, you will have to go to the CRM module and then Contact (1). At the page that will open you have to click on the Add Contact Button on the top right of the screen(2).

Then you have to fill out the fields of the Contact Data.

The meaning of the fields is as follows:

CampDescription
NameName of the Contact
SurnameSurname of the Contact
SalutationAllows you to Pin the greeting with which Refer to the contact (e.g. Lady or Miss)
StateEnable or Disable L Account
DepartmentThe Department to which the Contact belongs
QualificationThe status of the Contact
ManagerAllows Specifying a Contact Manager
SourceIndicates the source from which the Lead was generated
RatingCustomer Account Satisfaction Level
Associate userAllows Associating Contact to a System User on Deepser
TaskTask Related to Contact

Afterwards you have to complete the information of the user at the Contacts tab and fill out the fields.

The meaning of the fields is as follows:

CampDescription
EmailEmail of the Contact
TelephoneNumber of Fixed Telephony
Mobile phoneNumber of Mobile Telephony
FaxFax of the Contact
AddressAddress of the Contact
CityCity of Contact
ProvinceProvince of Contact
CAPCap of the Contact
StateState

After you have saved the newly created contact, you have to Sync it to a user. You have to go inside the contact and click on ‘Sync User’ on top right of the screen.

Password Reset

Change Password as admin

In order to change the password any  account, you will have to go to

 System->Permissions->Users and click on the user’s account you want to change the password to.

Here you can set the new password at the “Password” field (1) and confirm the password at the “Password Confirmation” (2) and simply save the changes (3)

Reset Password

To reset password of an account you will need the email address and the username of the user you want to reset the password. In the login screen you can see at the bottom of the login ‘Forgot your password?’.

 By clicking there you will be redirected to the page where you can reset your password.

In this page you should provide username and email address of the account. After you provide the required data click the button ’Recover Password’. If the email address and the username correspond to an user in Deepser a new email should arrive at the email address provided. The email should look like the one given below:

If you click the Reset Password button or link you will be redirected to a new page where you can add your new password.

The criteria for the new password are:

  • Should be at least 7 characters
  • Should contain at least 1 letter and 1 number

After adding the password and clicking Reset Password button the password will be set to the one you provided and you will be redirected to the login page.

Chat

Do you need more informations about of Deepser’s integrated Chat Advanced Configuration? We will explain everything about Public Channel, Chat Widget Integration, etc..

Articles

  • Using the Chat
  • Enabling the Chat on Portals
  • Chat Rooms and Moderators
  • Public Chat
  • Configure a Public Chat Widget
  • Chatbot
  • Chatbot Flow - Example

Using the Chat

Deepser offers an integrated chat, that allows you to collaborate internally with registered users, or receive requests from external users.

If properly configured, the chat module is accessible in two different ways:

1 – Using widgets, generally at the bottom right.

1b – The chat widget looks like this:

2 – By clicking on the Chat entry in the Deepser backend menu.

2b – This is how the backend chat module shows up:

NameDescription
ChannelsChannels where a certain number of users can communicate, possibly organized by topic.
DirectDirect communication between two users.

3 – To start communicating with a single user, press on the users icon.

4 – Select the user to start the chat with, then press Create Direct Chat.

5 – This is the direct chat section.

The meaning of the elements is the following:

ElementMeaning
Reply ButtonIt allows users to send normal messages in the chat, which can be viewed by the other participants of the group or by the recipient user.
Private Note ButtonIt allows the creation of a private note within the chat, not visible to other users.
Staple iconIt allows sending files as attachments in chat.
Emoji IconIt allows the insertion of an emoji in chat.
Send ButtonAllows you to send the message.

Enabling the Chat on Portals

1 – Access the system chat configuration, via System->Chat->Configuration

2 – To view the chat widget in the user portal, set “Enabled in Portal” as Yes,to make it available instead in the Guest portal, set Enabled in Frontend as Yes, finally press Save Config

Note: Public Chat Enabled Groups indicates the groups that will be enabled to manage public chat messages.

Max Attachment Size indicates the maximum size of attachments.

3 – To apply the configuration, reboot the Chat Websocket Server.

4 – Once the steps are completed, the chat widget will appear in the portals where it has been enabled.

Chat Rooms and Moderators

Deepser chat allows Key User, Agent and Admin to create Rooms .

Channels are spaces where multiple users can communicate, usually about a particular topic.

Let’s proceed with the creation of a channel.

1 – Press the Room creation button

2 – Enter a Name for the Room , and the list of participating users, then press Add room .

3 – Press on the three dots at the top left, then Edit Room.

 

4 – The channel editing menu will be displayed, with the possibility to add Moderator users.

This table describes the permissions of the room creator, moderators and end users.

 End UserModeratorsCreator
Edit/Delete RoomThey cannot create rooms or become moderators, but they can be added to a room .BothBoth
Edit/Delete MessagesThose of which it is senderAny messageAny message  
Add/Edit ModeratorsNoNoBoth
Remove the Creator from the ChannelNoNoNo

Note: As can be seen from the table, no one, not even the creator himself, can remove himself from one of his channels.

Public Chat

Deepser’s public chat, is a front-end chat available as a widget in any website or web service, through a script.

This type of communication, allows any unregistered user to send a message, which will then be managed in the Key User, Agent and Admin, if enabled.

Any communication made through the public widget, or in the guest portal, will appear in the Deepser backend, and will be identified by a unique code, representing the cookie released in the machine of the user who sent the message.

On the other left you can see the three statuses of a Public chat:

  • Not Assigned: The chat has yet to be assigned to a Key User, Agent or Admin, so any user correctly configured with one of these roles can see the message, but not respond until it is assigned.
  • Assigned: The chat is visible only to the assignee user, who can respond.
  • Resolved: The conversation has come to a conclusion.

To assign a chat, click on the icon at the top right, else to just choose to manage the request personally, click below the message.

To mark a conversation as resolved, press the tick button instead.

The user will then see the answer

Deepser’s public chat, is a front-end chat available as a widget in any website or web service, through a script.

This type of communication, allows any unregistered user to send a message, which will then be managed in the Key User, Agent and Admin, if enabled.

Any communication made through the public widget, or in the guest portal, will appear in the Deepser backend, and will be identified by a unique code, representing the cookie released in the machine of the user who sent the message.

Configure a Public Chat Widget

Deepser allows a website integration with the frontend chat, thanks to a dynamically generated script based on the parameters entered.

1 – Go to System->Chat ->Widget Configuration, then press ‘Add Widget configuration’.

2 – The widget configuration form will open, fill in the fields with the requested values, then Save.

This is the meaning of the fields:

FieldDescription
NameSets the name of the widget
DomainsSets the list of domains, from which it is allowed to call the widget, through the script
PositionSets the position where the widget will appear (bottom right/bottom left).
ColorSets the color of the widget.
TextSets the text that will appear in the bubble icon to open the widget.
Website NameSets the name of the website that will appear in the widget
Welcome TitleSets the welcome title that will appear once a user opens the widget for the first time.
Welcome TaglineSets the welcome subtitle that will appear once a user opens the widget for the first time.  
Can Send AttachmentsAllows the user to send files in the chat.
StatusThe status(Enabled/Disabled)
TokenIt’s the string that identifies the external implementation of the chat widget, it is automatically set when saved.
Widget ScriptField generated dynamically when saving, containing the scripting code, to be inserted to integrate the chat externally.

3 – Once saved, the token and the Widget Script will appear. This is the script to insert on the site to integrate the chat; copy the code by clicking on the scripting area.

3a– Enable Backend and Frontend to run in frame, in System->Configuration->Admin->Allow Backend to run in frame and Allow Frontend to run in frame

4 – insert the code on the page where you want the support widget to appear.

5 – If the integration was successful, the configured widget will appear at browser cache refresh.

6 – To enable groups to mange public chat messages, go to System->Configuration->Chat->Configurations, then set some groups in Public Chat Enabled Groups.

Chatbot

Chatbot – Flow

First of all, to trigger the flow the frontend must be enabled.

You can enable frontend on System -> Configuration.

After it, you must enable the chat on the frontend.
You can enable frontend on System -> Configuration -> Chat -> Configurations

Here, on Configurations -> Enabling, you will have to enable the “Enabled in Frontend” field.

The functionality behind the Bot in Deepser lies behind a flow with a trigger of type chatbot. The Chatbot flow trigger type is executed every time a new chat is created in the frontend area.

Create a Bot

  1. To create a bot, open System > Chat > Bot and click the button “Add Bot”.

2. Configure your bot

Field

Description

Name

The name of the Bot.

Flow Heather

The flow to which the Bot is connected.

Status

Status of Bot. It can be enabled or disabled.

Avatar

The image of Bot.

After it, we have to open the template of the chat. We must add to the form the field “Bot”.

Chat Bot Actions

Send Message

This action type is used to directly send a text message on the created chat.

To configure this, you need to open the “Send Message” script. For do this, click “”.

  1. Open: Action > Chat Bot > Send Message.

2. Write your message in the field called “Message” and, after it, click “Save”.

Ask For Details

This action is used to send a message in the form of a question that waits for a response.

The response can be of type String or Attachment. This response can be used as a variable later on the flow.

To configure this, you need to open the “Ask For Details” script. To do this, click “+”.

  1. Open: Action > Chat Bot > Ask For Details.

2. Write your message in the field called “Message” and after click “Save”.

Present Options

By using this action, on the chatbot will appear a message in the form of a select field from which the user can select only one answer and cannot type a custom message or add an attachment. The options are mapped through the “value” field which has the role of a key and the “label” field which is the visible option to the user.

To configure this, you need to open the “Ask For Details” script. To do this, click “+”.

  1. Open this: Action > Chat Bot > Present Options.

2. Write your message in the field called “Message”, insert your options on field “Options” and save clicking the button “Save”.

If you set the field “Add Variable Options” to “ON” you have the opportunity to add an array of options that are retrieved from upper steps of the flow and set to an output variable.

Chat With Operator

By using this action, the chat is assigned to a specific user present in Deepser who can be an administrator, agent, key user.

Frontend User
Backend User

With this action, the assigned user can then chat directly with the frontend user.

To configure this, you need to open the “Chat With Operator” script. To do this, click “+”.

  1. Open: Action > Chat Bot > Chat With Operator.
  1. Message

On this field is written the text that will be displayed on the chat, informing the frontend user that from now on their request will be assigned to an agent.

  1. Notification Message

This field contains the text message that will be sent to the assigned user.

  1. Operator

This field holds a variable of type DeepAdmin- User Model and here is where we assign the user variable retrieved from upper stages of the flow.

Chatbot Flow - Example

Introducion

On this page we will explain how to set up an example chatbot.

In this example, when a frontend user needs to have some information, the chatbot will assign the chat to the correct backend operator.

For this we will use three different users:

Trigger

First we will insert the type of trigger as Chatbot

From this block we will get the following variables:

Variable

Description

Bot

The model of the bot and contains all formtemplate fields.

Room

This variable represents the chat room.

All Room Form Fields

This variable contains all formtemplate fields of room model as an array

Block 1

In this block we will insert a welcome message into our frontend chat:

When the frontend user starts the chat, the message written in the “Message” field (image above) will be automatically sent to him.

From this block we will not get variables to use later if necessary.

Block 2

Here, let’s see how to ask the frontend user to enter their first and last name. This information will then be used to rename the room.

The message written in the field will be sent immediately after the welcoming one.

The user will reply to the message from the chat by entering the requested information.This information will be saved in the “Respond” variable.

With this block we will get the following variables:

Variable

Description

Response

The response entered by the frontend user

Attachments

The possible attachments inserted

Attachments Count

Sum of attachments

Block 3

With this block we are going to rename the chat room name on the backend side.

N°

Description

Note

1

Let’s choose the “Update Record” block.

This way we can change the name of the room

2

Let’s choose the chat room as our model.

The response is one of the variables obtained in the trigger (block 1)

3

Let’s enter the “Name” field in the query-builder, which will be valorized with the user’s response

The answer is one of the variables derived in block 3

Note: This configuration will work when the “Chat with Operator” block is added.

 

With this block we will get the following variable:

Variable

Description

(Model) DeepChat – Room

Room template with updated name

Block 4

In this block we will see how to insert three options of your choice.

N°

Description

Note

1

Let’s choose the “Present Options” block.

In this way we can create the options that will later be shown to the frontend user

2

Variables addition

Optional, in this example we take as input the name provided to the user.

3

Let’s enter the message that will appear as a header to the options

Here, the text {{var name}} is used to enter the user’s name, entered as input

4

Added options that the user will have available to them

 

The following message will be sent to the user:

Clicking the square of the chosen answer will automatically send the choice as if it had been written by the user

With this block we will get the following variables:

Variable

Description

Response

The response entered by the frontend user (string)

Value

Response value

Block 5

In this block, we will enter the condition “if option 1 was chosen.”

N°

Description

Note

1

Let’s choose the “If” block.

 

2

Let’s set the desired condition

In this case we set user-chosen value is “support incident/request”

Block 6

Entry into this block will only occur if the frontend user chooses “support incident/request”(1) as an option.

Here, we will retrieve the “Support” user, who will be the operator to whom the chat will be sent.

N°

Description

Note

1

Let’s choose the “Lookup Record” block.

This will allow us to retrieve the user “Support”

2

Let’s choose the model “DeepAdmin – User”

 

3

As a filter let’s enter the “user_id”

In this example, the user “Support” has id 53

With this block, we will get the following variables:

Variable

Description

(Model)DeepAdmin – User

Model with user data

Model Alias

For this model it will be “deep_admin/user”

Block 7

This block will handle the handover of the chat to the “Support” operator.

N°

Description

Note

1

Let’s choose the block “Chat with operator”

 

2

Field in which a message can be inserted for the frontend user

Optional

3

Field in which you can enter a message for the operator

Optional

4

The user retrieved in block 6 is inserted from the variables

Optional, if left blank it will be sent to all enabled users.

Block 8

In this block, we will insert the condition “if option 2 was chosen.”

N°

Description

Note

1

Let’s choose the “else If” block.

 

2

Let’s set the desired condition

In this case, the value chosen by the user is “sales problem/request”

Block 9

Entry into this block will occur only if the frontend user chooses “sales problem/request”(2) as an option. Here, we will retrieve the user “Sales,” which will be the operator to whom the chat will be sent.

N°

Description

Note

1

Let’s choose the “Lookup Record” block.

This will allow us to retrieve the user “Sales”

2

Let’s choose the model “DeepAdmin – User”

 

3

As a filter we enter the user_id

In this example, the user “Support” has id 54

With this block, we will get the following variables:

Variable

Description

(Model)DeepAdmin – User

Model with user data

Model Alias

For this model it will be “deep_admin/user”

Block 10

This block will handle the handover of the chat to the “Sales” operator.

N°

Description

Note

1

Let’s choose the block “Chat with operator”

 

2

Field in which a message can be entered for the frontend user

Optional

3

Field in which you can enter a message addressed to the operator

Optional

4

The user retrieved in block 9 is inserted from the variables

Optional, if left blank it will be sent to all enabled users.

Block 11

In this block, we will insert the condition “if option 3 was chosen.”

N°

Description

Note

1

Let’s choose the “else If” block.

 

2

Let’s set the desired condition

In this case, the value chosen by the user is “administration incident/request”

Block 12

Entry into this block will occur only if the frontend user chooses “administration incident/request”(3) as an option.

Here, we will retrieve the “Administration” user, which will be the operator to whom the chat will be sent.

N°

Description

Note

1

Let’s choose the “Lookup Record” block.

This will allow us to retrieve the user “Administration”

2

Let’s choose the template “DeepAdmin – User”

 

3

As a filter we insert the user_id

In this example, the user “Support” has id 55

With this block, we will get the following variables:

Variable

Description

(Model)DeepAdmin – User

Model with user data

Model Alias

For this model it will be “deep_admin/user”

Block 13

This block will handle the handover of the chat to the operator.

N°

Description

Note

1

Let’s choose the block “Chat with operator”

 

2

Field in which a message can be entered for the frontend user

Optional

3

Field in which you can enter a message for the operator

Optional

4

The user retrieved in block 12 is inserted from the variables

Optional, if left blank it will be sent to all enabled users.

CMDB

The cmdb in Deepser is a database made available to the user.

It is the tool used to create records (Custom item or CI) and store the information, organised by a Type, a Subtype and a Class.

In this course we will deal with the CMDB in all its parts.

Articles

  • Deepser CMDB
  • Enable CMDB in the User Portal
  • User Portal CMDB Grid Configuration
  • Advanced Configuration of CMDB Grids
  • Class, Type and Subtype
  • Configuring a CI

Deepser CMDB

The CMDB in Deepser is a database made available to the user.

It allows you to create records (Configuration item or CI), each of them characterized by a Type, a Sub Type and a Class.

Classes

Classes make it possible to distinguish ci into macro categories.

The defined macro categories will be displayed on the backend side inside the CMDB menu as shown in the figure below.

Types

Types allow you to add a type layer to the elements defined in the classes.

On one hand, it allows you a more granular management of visibility permissions.

On the other hand, it allows us to make it more immediate to understand what that particular refers to.

Subtypes

Subtypes allow you to add a type layer to the elements defined in the Types.

This allows on the one hand a more granular management of visibility permissions; on the other hand, it allows us to make it more immediate to understand what that particular refers to.

THE CI

As mentioned above, there are similar to records in a database that allow you to create custom entities within Deepser.

These entities can be assigned to users who will be able to view and edit these entities.

An example of use is for example the management of the devices assigned to the users, in this case once assigned the ci to the user, it will be able to display any information concerning the device itself for example serial number, any pins or associated codes or any other kind of information that may be useful to manage for the assignee user.

Types allow you to add a type layer to the elements defined in the classes.

This allows on the one hand a more granular management of visibility permissions; on the other hand, it allows us to make it more immediate to understand what that particular refers to.

Enable CMDB in the User Portal

To enable the cmdb in the user portal you will need to go to the menu: System->Configuration.

Here it will be a must to go to the “Portal” item.

At this point, the following screen will open:

You will need to set the “Enable” field to “Yes”, this will enable the CMDB for the user portal.

The default “Enabled Priority” field on “Global” allows you to specify whether the CMDB will be enabled for all users (default) or if set to “User” it will be enabled only for users for whom the Portal CMDB Visibility field has been set to “Yes”.

User Portal CMDB Grid Configuration

To configure the CMDB grid in the user portal, you will need to go to the menu: System->Portal->Ci.

Here you can configure the grid using the pencil button at the top left.

Once you click the pencil button, both will open the following screen:

Here, you can insert new fields in the grid by dragging them from the “Available Columns” column to the “Visible Columns” column.

As per the image below.

In addition, from here it will be possible to modify what will be visible through the configuration of the query builder, in the example below we want to make visible only those that belong to the “Locations” class.

Note that these configurations will apply to all end users, to make a more granular configuration it will be possible to implement a custom script, as we will see in the next lessons.

Advanced Configuration of CMDB Grids

In Deepser you can define a custom script that allows you to specify advanced conditions for the collection of us to be displayed.

Example 1

In this case we suppose we want to make visible only to some End-users all the categories of the  CMDB, all the others we want to display only on the CI of class 1 (Location).

To do this, we must go to the menu: System -> Portal -> CI.

Here, we will have to click on the pencil-shaped button.

Now the following screen will open:

In the “Prepared Collection Script” section, we are going to insert the following code:

				
					//Array of technicians, who can see all the cis
$technicians = ['deepser_tec','mario.rossi'];
 
//if the current user is not in the technicians array he or she colud only see cis with class_id 1
if((!is_null($technicians) && is_array($technicians)) && (!(in_array(Deep::helper('deep_admin')->getCurrentUser()->getUsername(),$technicians)))){
     $this->getCollection()->addFieldToFilter('class_id', [ "eq" => 1 ]);
}
				
			

Note: that the array technicians contain the usernames of the users and not the Display usernames.

Once this is done, you will need to click on the “Save” button to save the changes.

Example 2

In this case we suppose we want to make visible only to some End-users all the categories of the CMDB, all the others we want to have visibility only on the class 1 CI (Location), compared to the previous case in this case we are going to define a custom field of checkbox type that will allow you to define in a simpler way    which users will be able to view all the ci.

To create the custom field, we must go to the menu: System -> Custom Fields

Here we will have to go in user model.

At this point in the “Fields” section, we are going to click on the “Add Field” button.

Now the following screen will open:

Here we are going to define the “Code” field as “is_cmdb_technician”.

The “Label” field will instead be “Is Technicians”.

Now, we configure “Column type” as “Integer”.

At this point, we define the “Element Type” field as “Checkbox”.

As a last step, going to the “extra” tab we set the flag: “Render as Toggle” to “Yes”.

At the end, click on the “Save” button to save the custom field.

At this point, it will be necessary to insert the newly created field in the users’ template form, and we will enhance it for those users who will have to see all the CI.

Now to implement the actual filter, we must go to the menu: System -> Portal -> CI.

Here, we will have to click on the pencil-shaped button.

Now the following screen will open:

In the “Prepared Collection Script” section, we are going to insert the following code:

				
					$userArray = Deep::getResourceModel('deep_admin/user_collection')->addFieldToFilter('cust_is_cmdb_technician',[ ["neq" => 1], ['null' => true]]);
 
$userlist = [];
foreach($userArray as $user){
  $userlist[$user->getUsername()] = $user->getDisplayUsername();
}
if(( !is_null($userlist) && is_array($userlist)) && (array_key_exists(Deep::helper('deep_admin')->getCurrentUser()->getUsername(),$userlist))){
     $this->getCollection()->addFieldToFilter('class_id',["eq" =>1]);
}
				
			

Once this is done, you will need to click on the “Save” button to save the changes.

Class, Type and Subtype

In Deepser Cis Class, Type and SubType are organized in hierarchical ways starting from the highest level of the hierarchy we have the classes; each class can then be associated with one or more Types and at the end of each Type will be associated one or more SubTypes.

In this guide we will see how to configure the hierarchy of classes, Type and SubType.

Class

To configure a new class, you will need to go to the System -> CMDB Configuration-> Class menu.

Here, you will need to click on the “Add Class” button.

At this point, the following screen will open:

Below is a table with the name of the fields and their meaning:

FieldDescription
NameThe name of the class.
StatusThe Status of the class, if “Enabled” the class will be displayed otherwise it will be  neither  viewable  nor  setable and with it will also be hidden the ci of that class.
Enabled GroupsGroups that can see that class and interact with the
IconClass icon, it is used to make it easier to recognize the class at first glance.
PositionPosition of the class, this field will allow you to define the order in which the classi will be displayed in the sidebar.

Once you have filled in the fields in the desired way, you can click on the “Save” or “Apply” button to save the class

Type

To configure a new Type, you will need to go to the System -> CMDB Configuration-> Type menu.

Here, you will need to click on the “Add Type” button.

At this point, the following screen will open:

Below is a table with the name of the fields and their meaning:

FieldDescription
ClassThe class to which the Type belongs.
NameThe Name of the Type.
StatusThe Status of the Type, if “Enabled” the Type will be displayed Otherwise essor will not be viewable or settable.
IconClass icon, it serves to make it easier to recognize the Type at first glance.
PositionLocation of the Type, this field will allow you to define the order in which the Types will be displayed.

Once you have filled in the fields in the desired way, you can click on the “Save” or “Apply” button to save the  type.

SubType

To configure a new Subtype, you will need to go to the System -> CMDB Configuration->SubType menu.

Here you will need to click on the “Add SubType” button.

At this point, the following screen will open:

Below is a table with the name of the fields and their meaning:

FieldDescription
TypeThe Type to which this Subtype will be associated.
NameThe Name of subtype.
StatusThe Status of the Subtype, if “Enabled” the Subtype will be displayed Otherwise essor will not be viewable or settable
IconSubtype icon, it is used to make it easier to recognize the Subtype at first glance.
PositionLocation of the Subtype, this field will allow you to define the order in which the Subtypes will be displayed in the sidebar.

Once you have filled in the fields in the desired way you can click on the “Save” or “Apply” button to save the Subtype.

Configuring a CI

To create a new CI in Deepser you will need to go to the menu: CMDB-> All.

Here you can click on the “Add Us” button.

Now in the window that will open you will need to choose the type of us to create and then click on the “New” button.

At this point, the following screen will open:

Below is the name of the fields and their meaning:

NameMeaning
NameName that will be associated with the new CI.
CategoryThe category associated with what you are creating. 
ClassThe class of CI.
TypeThe Type of the
SubtypeThe SubType of the CI.
DescriptionDescription Del CI.
Serial NumberSerial Number  of the CI.
Front ImageFront image of the CI.
Business ImpactImpact on the business of the CI in question. This field indicates how important this is to the company’s business.
PriorityPriority of the CI.
UrgencyUrgency of the CI.
NotesNotes Associated with this there.

In the “User Details” tab, there will be the following fields:

Below is the name of the fields and their meaning:

NameDescription
Owner CompanyCompany that owns the company
Owner GroupGroup owner of the CI
Owner UserUser owner of the CI.
Assigned CompanyCompany assigned to us
Assigned GroupAssignee group of the CI
Assigned UserUser assignee of the CI.
Updated ByThe last user who updated the CI, at the beginning will be the user who created the CI.

In the “Activity/Attachments” tab, there will be the following fields:

Below is the name of the fields and their meaning:

NameDescription
TaskTasks Associated with CI. Before we can enter tasks associated with this, we will need to save it at least once.
ActivitiesActivities associated with the CI, could be comments or worklogs associated for example with the maintenance of the CI.
AttachmentsAttachments of the CI, this field can be used to upload files that regarding a CI.

In the “Relations” tab there will be the following fields:

Below is the name of the fields and their meaning:

NameDescription
Relation to Other CIsThis field will show relationships with others there (when present)

In the “History” tab, there will be the following fields:

NameDescription
History ChangesThis field will contain the list of changes made to this field so that you know who made changes on it.

Once you have filled in the fields, you can click on the “Save” button to save the CI just valued.

New User Registration

In Deepser it is possible to implement a user registration procedure to allow new users to register independently among the users present in Deepser.

Below, we will cover the procedure necessary to implement the creation of a registration form in Deepser.

CREATION OF THE NECESSARY STEPS

Deepser allows you to create a registration form by combining one or more Step components.

To create a “Step” you will need to go to the “System -> Permissions -> user Registration -> Step” menu

In the screen that will open, you will need to click on the “Add Step” button.

Once you click the button, you will be redirected to the creation screen of a new step.

Below we briefly report the meaning of each field:

FieldDescription
NameStep name
PositionPosition in the step grid.
LabelWritten that will appear to users when the step is uploaded.
Is Default stepIndicate if this is the step from which the recording will begin
Is Final stepIndicate if this is the step that will end the recording
Next stepNext step in the registration, null if the current step is the step that will end the registration
Check TokenChecks whether the verification token is present in the request.
Send TokenSubmit the verification token
Token DurationToken duration in hours and minutes
MailboxIndicates the mailbox with which the messages will be sent to the user during registration
Email EventEmail event associated with registration (if any)
StepData FormtemplateForm template associated with the current step
Validate ExpressionCustom code that allows you to validate the input data
Final MessageFinal message that will be displayed by the user if the current step is set as the final  step
Create UserIndicates whether a user will be created in this step
Create Active UserIndicates whether an active user will be created in this step
Send Reset PasswordIndicates whether a password reset email will be sent to the user
Field ConfigMapping user principal fields to form template fields
User Create ExpressionCustom code that will be used to create a user
StatusIndicates whether this step is active or not.

Registration Form Creation Example

In the successive lessons we will cover the creation of a registration form that allows a user to register himself and access the support, but only to users who belong to a company registered in Deepser, this to prevent external users from opening tickets without permission.

CREATING A CUSTOM FIELD TO RECEIVE USER INPUT

Before proceeding with the actual creation of the form, we must create a custom field that allows us to receive user input.

In the following example, we will see how to create a user only if the VAT number entered will correspond to one of the companies present in Deepser. For this example,  we will assume that there is a custom field named “cust_vat_number” that will contain the VAT number of the company.

The Custom Fields will be addressed in another lesson, to go to the lesson related to the Custom Fields click here.

To create a custom field, we must go to: System -> Custom Fields.

Here we will have to click on the model “DeepRegistration – stepData”.

On the next screen, we will have to click on the “Add Field” button.

In the screen that will be displayed, will need to fill in the fields as follows:

Important is to set the “Column Type” and “Element Type” fields to text.

At this point, you will need to click on the “Save” button

Once this is done, we can proceed to implement the registration form.

Form Creation

In order to create the Registration Form we must go to the step creation menu to create a new step.

The Step Section is located under the “System-> Permissions – > user Registration -> Step” menu.

At this point, we give a name to our registration form by entering the desired name in the “Name” field

We define the “Position” field as zero.

Now we set the label that will be displayed on the registration screen by entering the desired text in the “Label” field.

Note that this field can contain text or even html with its css styles.

We define “Is Default Step” field to yes, in this way we are defining what will be the step from which the registration will begin.

Since in our example we have only one registration step, we also define “Is Final Step” to “Yes”.

Since in our example we have only one registration step we define “Next Step” as  none, in the case of a multistep registration it will be possible to set what will be the next step, through this field.

Another important thing to notice is that to populate the field, you will first need to create a new step.

We set what will be the email box that we will use to send any Password change emails through the “Mailbox” field

Now we set which form template we want to display during registration using the field “StepData  Formtemplate”

In the “Validate Expression” field, we can go to define the custom code that we will need to carry out checks on the validity of the data passed in input.

Within this field we are going to enter the following code:

				
					/**Defining Variables**/
 
//Assigning StepDatas to a variable.
$stepData = $this->getStepdata();
 
//Assigning the value og the cust_vat_number field to a variable.
$vatNumber = $stepData->getData('cust_vat_number');
 
//Assigning the value of the email field to a variable.
$email = $stepData->getData('email');
 
//if the email isn't in a valid format return an error to the user.
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
     $this->addError("Email is not in a valid format");
}
//Retriving form the user collection all the users the have the username equivalent to the ginven e-mail.
$usersCollection = Deep::getResourceModel("deep_admin/user_collection")->addFieldToFilter("username",["eq" => $email]);
//Retriving form the user collection all the StepData the have the username equivalent to the ginven e-mail.
$stepDataCollection = Deep::getResourceModel("deep_userregistration/stepdata_collection")->addFieldToFilter("email",["eq" => $email]);
 
//If uone or more user or StepDatas where found retun an error to the user.
if($usersCollection->count() || $stepDataCollection->count()){
     $this->addError("Email Already Registered");
}
 
 
/**If the company is present in Deepser we allow the registration otherwise throw an error**/
 
//Loading a company ginven the cust_piva field, if there is non company with this field this method retrive a new object.
$company = Deep::getModel("deep_company/company")->load($vatNumber,'cust_piva');
 
//If the returned object doesen't have the id or is null,return a error to the user.
if(!($company && $company->getId())){
    $this->addError("We are sorry, but only employee of our customer can register an account");
}
				
			

In the field “Final Message” we will define the message that we will give to the user once the registration has been successfully completed.

Here, we will insert the following code:

				
					<style>
    .cust__msg{
        margin-left: auto;
        margin-right: auto;
        display: flex;
        flex-direction: column;
    }
    .cust__msg > *{
        text-align: center;
        box-sizing: border-box;
        margin-left: auto;
        margin-right:auto;
        width: 100%;
    }
    .cust__msg .row{
        display: flex;
        justify-content:space-evenly;
        padding-right: 30%;
        padding-left: 30%;
    }
 
</style>
 
 
 
<div class="cust__msg">
    <h1>Success</h1>
    <p>Congratulations, your account has been created!.</p>
    <div class="row">
        <div class="col-sm-3">
            Username: 
        </div>
        <div class="col-sm-3">
            <?php echo $this->getStepdata()->getData('email');?>
        </div>
    </div>
    <div>
        <h6>We have sent you an email with the link to reset your password.</h6>
    </div>
</div>
				
			

At this point, we will have to define to create a user by defining the field “Create User” to”Yes”.

Now, we will define if the user will be an active user by defining the field “Create Active User” to “Yes”

Now we will define whether to send the user an email at the end of the procedure that will allow him to reset the password using the “Send Reset Password” field.

Now, in the “Field Config” field we will define the mapping of the user template fields with the form fields. To add a new field to map with the form data simply click the “+” button.

We have defined the users’ field as follows:

In the “User Create Expression” field, we can define custom code that will allow us to set the user’s attributes  or in general to perform actions when creating a new user. In this field, we will enter the following code:

				
					//getting the datas from the form
$stepData = $this->getStepdata();
// assigning the end user role to the created user by passing the role id
$this->getUser()->setData("role",73);
				
			

Finally, we set the “Status” field to Enabled (If it wasn’t already set to Active).

At this point, you will need to click on the button “Save” or “Apply”

Editing the form template

To modify the form template that will be displayed during registration, you will need to click the “Preview” button

At this point, you will need to click the pencil button:

And then go to the StepData tab:

Here you can enter the fields by dragging them from the right column into the grid

Finally, you will need to click on the Save Button.

Token usage

During the registration phase it may be necessary to validate the user’s email, to do this you can send a token that will allow you to verify the user’s email.

Taking as a basis the previous example, we create another step, this time ignoring the part related to the creation of the account, in addition we will configure the sending of the token.

EMAIL TEMPLATE CREATION

In order to send the verification token to the end user it will be necessary to create an email event with its associated template form that will be used by Deepser to send the email to the user who is registering.

To create a custom mail event you will need to go to the System -> Tools ->  Email -> Templatemenu.

Then you will need to click on the “Add MailTemplate” button.

In the screen that will open you will need to define a name for the template, to do  this, simply enter the desired name in the “Name” field.

Next, we will define a code for the template, filling in the “Code” field.

At this point, it will be possible to insert in the “Subject” section the php code that will compose the subject of the email.

You can use the following code as a reference to compose the subject of the email:

				
					<?php echo Deep::helper('deep_email')->__('DEEPSER - Confirm your Registration')?>
				
			

Now it will be possible to insert in the section  “Body”, that will represent the content of the message, the PHP / HTML code that will serve to generate the body of the  mail.

You can use the following code as a reference when creating the body:

				
					<?php
$username  = $this->getModel()->getEmail();
$firstname = trim($this->getModel()->getFirstname());
$lastname  = trim($this->getModel()->getLastname());
$tmpFullname = $firstname . $lastname;
$fullname = $fullanme != "" ? $tmpFullname : "user";
$url = $this->getModel()->getTokenStepUrl();
?>
<?php $this->includeTemplate("header") ?>

<!-- Start of Main Content -->
<tr style="">
<td bgcolor="#FFFFFF" align="center" style="">
<table width="100%" align="center" cellpadding="0" cellspacing="0" border="0" class="devicewidth" style="">
<tbody style="">
<!-- Start Spacer -->
<tr>
<td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
<td class="h26" height="36" style="font-size:1px; line-height:1px;">&nbsp;</td>
<td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
</tr>
<!-- End Spacer -->
<tr style="">
<td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
<td class="mktEditable content mktEditable content" id="edit_text_1" valign="middle" style="font-family:Calibri, Helvetica, sans-serif; font-size:16px; color:#505050; text-align:left; line-height:25.6px; font-weight:normal; text-transform:none;">
<p>
<br>
<?php echo Deep::helper('deep_email')->__('Dear %s',$fullname);?>,<br>
<?php echo Deep::helper('deep_email')->__('Please confirm your registration by clicking the link below'); ;?><br>
</p>
</td>
</tr>
<!-- Start Spacer -->
<tr>
<td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
<td height="30" style="font-size:1px; line-height:1px;">&nbsp;</td>
<td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
</tr>
<!-- End Spacer -->
</tbody>
</table>
</td>
</tr>
<!-- End of Main Content -->
<!-- start of Button -->
<tr style="">
<td bgcolor="#FFFFFF" align="center" class="mktEditable" id="edit_cta_button" style="">
<table width="100%" border="0" cellspacing="0" cellpadding="0">
<tbody>
<tr>
<td class="w22" width="41" style="font-size: 1px; line-height: 1px;">&nbsp;</td>
<td align="left">
<table class="button" cellpadding="0" cellspacing="0" border="0" align="left" bgcolor="#0080ff" style="-webkit-border-radius: 4px; -moz-border-radius: 4px; border-radius: 4px;">
<tbody>
<tr>
<td width="518" align="center" valign="middle" height="65">
<span style="color: #ffffff; text-decoration: none;">
<a class="mobButton mktNoTok" href="<?php echo $url ?>" style="font-family: Calibri, Helvetica, sans-serif; font-size: 16px; color: #ffffff; display: block; height: 65px; mso-line-height-rule: exactly; line-height: 65px; font-weight: normal; text-decoration: none; text-align: center!important;" target="_blank" title="Link al ticket">
<?php echo Deep::helper('deep_email')->__('Confirm the registration')?>
</a>
</span>
</td>
</tr>
</tbody>
</table> </td>
<td class="w22" width="41" style="font-size: 1px; line-height: 1px;">&nbsp;</td>
</tr>
</tbody>
</table>
</td>
</tr>
<!-- end of Button -->
<?php $this->includeTemplate("footer") ?>
				
			

And click on the “Save”  or “Apply” button:

EMAIL EVENT CREATION

To create a custom mail event, you will need to go to the “System -> Tools ->  Email -> Event” menu.

At this point, you will need to click on the “Add Event” button.

The following page will be displayed:

At this point, it will be necessary to give a name to the event by filling in the “Name” field.

We define Whether to send attachments, changing the value of the field “Send Attachments”, in our case we set it to  “No”.

Now, in the “Email Template” field, we select the template created in the previous point of this guide.

In the “Event Trigger”section, select “DeepUserregistration-StepData”  in the “Model” field

In the “Event Expression” entry.

We insert the following code :

				
					return true;

				
			

In the “To” section

We insert the following code :

				
					/**Configuring the language with local **/
$this->changeLanguage($this->getModel()->getCustLocale());
/**Getting the email from the current model**/
$this->addTo($this->getModel()->getEmail());
				
			

At this point, we can go to click the “Save” or “Apply” button

Now the event will have been saved.

ADD A NEW FORM TEMPLATE

To create a new form template, you will need to click on “Preview”.

Here, you will need to click on the button with the arrow icon.

Now you will need to click on “New Formtemplate”

In the screen that will open, you will need to enter in the field “Enter Template Name” the name of the new form template.

Next, you will need to click on “Save”.

At this point, the new form template will be created.

SET A FIELD AS REQUIRED

To create a new form template, you will need to click on “Preview”.

Here you will need to click on the button with the pencil icon.

Here you will need to go to the “Fieldset”:  “Step data”.

At this point it will be necessary to locate the field that we want to make mandatory and click on the corresponding gear icon.

In the screen that will open you will need to change the field “Required” and set it to “Yes”.

Now you will need to click on the “OK” button on the field configuration screen.

Finally, you will need to click on the “Save” button in the form configuration window.

At this point the field will be mandatory.

EDIT FORM TEMPLATE PRIORITY

Deepser evaluates form templates from the highest priority to the lowest priority form templates.

The priority of the form templates is therefore important to define which form template the user will see.

To set the priority, you will need to go to the arrow key.

Now click on the template you want to edit.

At this point, click on the button with pencil icon.

Now you will need to click on the “Edit  Rules” button and then subsequently set a value in the  priority field.

Finally, click on the “Save” button.

STEP CREATION

For this example we will use as a basis the step created in the previous lessons, in addition we will create two form template the first named “First” with the email fields, Firstname  and  Lastname and the second named “Second” with only the  Vat  Number field (cust_vat_number) created in the previous points  of lessons of this guide.

INITIAL STEP

Let’s go to the Step section and click on the “Add Step” button

In this new we are going to configure the field “Name”, in this field we will enter the name we want to give to the step.

We configure the field “Position” to 0

We configure the field The “Label”, this field will contain the  inscription  that  the user will see when he arrives at this form.

We configure the field “Is  Default  Step”  to  “Yes”.

We configure the field “Is Final Step” to “Yes”.

We configure the “Next Step” field on the step created in the previous points (User Support Registration).

We configure the field “Check token”  to  “No”.

We configure the field “Send Token”  to  “Yes”.

We set the “Token Duration”field, to an hour or at least to the time that we believe to be sufficient to perform the registration.

We configure the”Mailbox”fieldwith the exit mailbox that we will use for registraction.

We configure the “Email Event”fieldwith  the mail event created in the point above.

At this point we set the field”StepData Formtemplate” form template that we want to use in this first step, in the template form we set all the fields that must be filled in as mandatory, in this way the user will have to fill them in order to continue, you can refer to the previous topic for the configuration of the form field as mandatory  click here to go to the guide.

To create a custom form template you can follow the guide found in the previous article, click here to go to the guide.

We can configure the fields “Create  User”  and  “Create Active  User”  to  “No”.

In the “Validate Expression” field, we insert the following code to verify the form template.

				
					/**Variables Initialization**/
 
//Assigning the stepDatas to a variable.
$stepData = $this->getStepdata();
 
//Assigning the value of the email field to a variable.
$email = $stepData->getData('email');
 
/**Verifications**/
 
//if the emil isn't in a valid format return an error to the user.
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
     $this->addError("Email is not in a valid format");
}
//Retriving form the user collection all the users the have the username equiva-lent to the ginven e-mail.
$usersCollection = Deep::getResourceModel("deep_admin/user_collection")->addFieldToFilter("username",["eq" => $email]);
//Retriving form the user collection all the StepData the have the username equivalent to the ginven e-mail.
$stepDataCollection = Deep::getResourceModel("deep_userregistration/stepdata_collection")->addFieldToFilter("email",["eq" => $email]);
 
//If uone or more user or StepDatas where found retun an error to the user.
if($usersCollection->count() || $stepDataCollection->count()){
     $this->addError("Email Already Registered");
}
				
			

In this case we can leave the field “Field Config” as we are going to manage the creation of users in the last step

We can leave the”User Create Expression”field blank because we will not create users in this step.

At this point, Click on the Apply or  Save button.

In the end, the step will be saved.

FINAL REGISTRATION STEP

Let’s move now on to the final registration step.

In this step, we are going to change the”Check  Token”field by setting it to  “Yes”.

And we will configure the form template that will be associated with this template using the field “StepData  Formtemplate”.

At this point, we modify the Form Validate Expression field to perform the only validation of the “Vat  Number” (in the case of example).

				
					**Defining Variables**/
 
//Assigning StepDatas to a variable.
$stepData = $this->getStepdata();
 
//Assigning the value og the cust_vat_number field to a variable.
$vatNumber = $stepData->getData('cust_vat_number');
 
/**If the company is present in Deepser we allow the registration otherwise throw an error**/
 
//Loading a company ginven the cust_piva field, if there is non company with this field this method retrive a new object.
$company = Deep::getModel("deep_company/company")->load($vatNumber,'cust_piva');
 
//If the returned object doesen't have the id or is null,return a error to the user.
if(!($company && $company->getId())){
    $this->addError("We are sorry, but only employee of our customer can register an account");
}
				
			

Note: this form template must have a higher priority than all the others

At this point, you will need to click on the “Save” or “Apply” button.

Enabling Registration

To enable the possibility of registering through the registration form, it will be necessary to go to the System -> Configurations  -> Admin -> Security menu.

Here you will need to change the field “Enable User Registration” and set it to “Yes”.

Now, to save the changes, you will need to click on the “Save Config”button.

At this point, the registration link will have appeared on the main Login page:

Documentation

Articles

  • Access and Visibility
  • Activity, Worklogs & Comments
  • Board
  • Categories
  • Chat
  • CMDB
  • CRM
  • Deepser API
  • Deepser Fundamentals
  • Email Integration
  • Escalation
  • Importing Data
  • IT Asset Management
  • Knowledge Base
  • List
  • Password Management
  • Relations
  • Service Management
  • SLA
  • Task
  • Workflow
  • Inventory
  • Custom Fields
  • Custom Event
  • Dashboard
  • Project
  • Calendar
  • Survey
  • Contract and Contract Line
  • Report Documentation
  • Sales
  • Integrations

Access and Visibility

This Course will give you a better knowledge on how Rights, Permissions and General Visibility Works in every Deepser’s Module. We will talk about Users, Groups, Roles and Companies from the System Admin Perspective.

 

Resources

In Deepser the resources are basically the modules or service that Deepser makes available.

An example of the exposed resources is shown below.

The visibility of  the resources in Deepser can be set up to the model level.

The user will only be able to see modules and resources that have been set as visible to the membership role.

Roles

In Deepser, roles are used to define which resources the user will have access to.

We can exemplify the concept roles manage Vertical visibility in Deepser, that is, the visibility of the modules presents in the sidebar

THE MAIN ROLES IN DEEPSER AND THE PREDEFINED ROLES

The default roles in Deepser are:

RoleDescription
AdmininstratorAdministrators Users in Deepser, are users that have global access and bypass the limits of visibility in the backend, in addition to them have faculty to modify the grids and form templates. This is the only role that has access to the system configurations and the System tab.
Super AdminSuper Admins are users with Administrator role who have set “All” in the resource visibility section. This role is the only one that has access to scripting areas.
AgentsThese Users have the right to modify the grids and form templates, but they do not have access to the scripting areas or even to the modules placed in the System tab. For the rest by default, they have global access to all other modules.
Key UsersThese users are comparable to Agents users, but unlike the latter they have no ability to modify any system configuration, including grids and form templates.
UsersThese are the end users, as a rule, these users do not have access to the backend but only to the end user portal. Since they do not have access to the backend, they cannot change any system configuration or even see the tickets that have not been opened by them. If there is a need for an end user to see tickets not opened by himself, he can be modified by setting him as a Company Supervisor, in this case the user will be able to see all the tickets created by his company. Alternatively, you can configure the user as empowered user, this will give him visibility even on tickets not belonging to his company.
 

Creating and Managing Roles in Deepser

In deepser, roles are an important component in visibility management.

The roles allow you to manage the visibility of the modules accessible to user accounts (e.g. password, crm etc) or even which users can access the Deepser backend and which can only access the user portal.

Creating a Role

To create a role in Deepser you will have to go to the “System the Permissions->Roles”  menu.

At this point in the screen that will open you will have to click on the “Add New Role”

On the next screen you can set the “Role Name” field which will define the name that will have the new role.

In the type field it will be possible to define the Type that will have this role by compiling the “Type” field.

Then moving to the “Roles Resources” tab you can define which resources will be visible to the user to whom this role will be assigned by configuring the “Resource Access” field to Custom an selecting the resources you want to expose to this role.

Note: if you want to set the role to have no visibility limitations you can opt to select from the drop-down menu the item “ALL” instead of the item “Custom”, in this way no visibility limitations will be applied on the role (however this will not affect the visibility configured for groups).

Now click on the  “Apply” or on the  “Save” button.

Once the role has been created, a third item will appear in the list of tabs: Role Users.

Using this tab you can get a quick overview of all the users who have been assigned that role.

Creating a new user

A user in Deepser is an individual who interacts with the system, utilizing its features and functionalities.

To create a new user in Deepser you will need to go to the menu System  ->  Permissions  -> Users(1)

In the screen that will open, you will need to click on the “Add User” button(2)

At this point, the following screen will open:

FieldDescription
AvatarProfile picture of the user.
UsernameUsername of the user, this will serve to log in, this is a mandatory field to create and in addition this field must be unique within Deepser.
FirstnameThe name of the user. This is a required field
LastnameUser’s lastname.
EmailUser’s email
PasswordPassword of the user, note that this field is always white because the user’s password is not stored in a database format that is invertible, consequently the field remains unvalued by default even if the user has a password set, except when changing the password itself. In case of changes to this field when saving the user Deepser will automatically update the value of the password present in db.
Password ConfirmationConfirm the user’s password, like the previous field, this is also not valued except when changing the password itself.
RoleThe role of the user, depending on the role the user will have different visibilities on the various parts of the product. For example the Users role, who by default sees only the End User Portal. The roles of the users will be deepened in the dedicated Lesson, click here to go to the corresponding lesson.
ActiveIndicates whether the user is authorized to access Deepser. If the value is “Active” the user will be enabled to access, if the value is “Inactive” then the user will not be authorized to access Deepser.
Startup PageThis field indicates which is the default page to which the user will be redirected after logging in.
LocalIndicates the language in which the user visualizes Deepser interface
TimezoneIt indicates the time zone associated with that user, it is important to indicate the correct time zone so that Deepser can correctly set the format of the dates in notifications and date fields.
CompanyThe company field indicates which company the user belongs to, this field is very important since Deepser companies are one of the key elements in visibility management. The companies will be analyzed in the following lessons, click here to go to the lesson on the companies.
Additional CompaniesAdditional companies indicate to the data of which other companies the user will have access. This topic will be deepened in the lesson on company, this field will be selectable only after the user has been saved at least once
Is SupervisorThis field indicates whether the user will be a company supervisor. A company supervisor will have the ability to view and modify the tickets created by the users of his company
Company VisibilityThis field indicates if the user will have limited visibility to Company Data
Portal CMDB VisibilityThis field indicates if the user will see the cmdb in the user portal.
OTL TokenThis token if passed as a parameter (token) in the url of the request (query string) allows you to access Deepser without logging in. Note that the setting of direct access by token is by default disabled for security reasons, in addition for security reasons this token has validity of only one use, after which it is automatically reset by the system, this is done to avoid data theft.  
rp_tokenThis token is used to reset a user’s login credentials. This is a system field, at the operational level there is no use for this field.
LDAP SSO Identifier Field ValueA system field used to map the correspondence between users from AD and those from sso
API TokenThis is the “Barer Token” for access to Deepser’s A.P.I. (Application Programming Interface) To go to the course Deepser’s A.P.I. click here
EmpoweredIndicates if the user is an Empowered user, Empowered users are end users who are not limited to seeing only tickets for which they are requesters or whose company is the requesting company.

Once you have filled in the fields, you will need to click on the “Apply” or “Save” button.

Add the user directly in a group

After you have created the user you can add it directly in a group by going into the ‘’Groups’’ tab(1) and clicking Add(2).

In the following screen that will open, you will have to check the group(s) that you want the user to be added to(1) and select the action add and then submit it(2).

Then you simply have to close the window and the groups the user is included in will be shown in the “Groups” Tab.

Creating a user from an operation

Another way to create a user is directly from an operation(ticket). To do so go to the Service(1) Module and afterwards go inside a ticket.

To create a new user you have to click on the user+ icon at the Requester fieled(2) and a window will pop up. All you have left to do is fill out the necessary fields explained at the table above.

Another case is when the ticket is created with an email, without a user, like this.

All you have to do is click on the user+ icon at the Requester Field and at the window that will pop up, the email field would be automatically filled for you, so you have to complete the rest of the fields.

Note: On user creation, the default role will always be “Users” (in “Role” field), which identifies an end user. Remember to change the role according to your needs. You can check available roles here.

Create a user from CRM Contacts

To create a user from the CRM Contacts, you will have to go to the CRM module and then Contact (1). At the page that will open you have to click on the Add Contact Button on the top right of the screen(2).

Then you have to fill out the fields of the Contact Data.

The meaning of the fields is as follows:

CampDescription
NameName of the Contact
SurnameSurname of the Contact
SalutationAllows you to Pin the greeting with which Refer to the contact (e.g. Lady or Miss)
StateEnable or Disable L Account
DepartmentThe Department to which the Contact belongs
QualificationThe status of the Contact
ManagerAllows Specifying a Contact Manager
SourceIndicates the source from which the Lead was generated
RatingCustomer Account Satisfaction Level
Associate userAllows Associating Contact to a System User on Deepser
TaskTask Related to Contact

Afterwards you have to complete the information of the user at the Contacts tab and fill out the fields.

The meaning of the fields is as follows:

CampDescription
EmailEmail of the Contact
TelephoneNumber of Fixed Telephony
Mobile phoneNumber of Mobile Telephony
FaxFax of the Contact
AddressAddress of the Contact
CityCity of Contact
ProvinceProvince of Contact
CAPCap of the Contact
StateState

After you have saved the newly created contact, you have to Sync it to a user. You have to go inside the contact and click on ‘Sync User’ on top right of the screen.

Password Reset

Change Password as admin

In order to change the password any  account, you will have to go to

 System->Permissions->Users and click on the user’s account you want to change the password to.

Here you can set the new password at the “Password” field (1) and confirm the password at the “Password Confirmation” (2) and simply save the changes (3)

Reset Password

To reset password of an account you will need the email address and the username of the user you want to reset the password. In the login screen you can see at the bottom of the login ‘Forgot your password?’.

 By clicking there you will be redirected to the page where you can reset your password.

In this page you should provide username and email address of the account. After you provide the required data click the button ’Recover Password’. If the email address and the username correspond to an user in Deepser a new email should arrive at the email address provided. The email should look like the one given below:

If you click the Reset Password button or link you will be redirected to a new page where you can add your new password.

The criteria for the new password are:

  • Should be at least 7 characters
  • Should contain at least 1 letter and 1 number

After adding the password and clicking Reset Password button the password will be set to the one you provided and you will be redirected to the login page.

New User Registration

In Deepser it is possible to implement a user registration procedure to allow new users to register independently among the users present in Deepser.

Below, we will cover the procedure necessary to implement the creation of a registration form in Deepser.

CREATION OF THE NECESSARY STEPS

Deepser allows you to create a registration form by combining one or more Step components.

To create a “Step” you will need to go to the “System -> Permissions -> user Registration -> Step” menu

In the screen that will open, you will need to click on the “Add Step” button.

Once you click the button, you will be redirected to the creation screen of a new step.

Below we briefly report the meaning of each field:

FieldDescription
NameStep name
PositionPosition in the step grid.
LabelWritten that will appear to users when the step is uploaded.
Is Default stepIndicate if this is the step from which the recording will begin
Is Final stepIndicate if this is the step that will end the recording
Next stepNext step in the registration, null if the current step is the step that will end the registration
Check TokenChecks whether the verification token is present in the request.
Send TokenSubmit the verification token
Token DurationToken duration in hours and minutes
MailboxIndicates the mailbox with which the messages will be sent to the user during registration
Email EventEmail event associated with registration (if any)
StepData FormtemplateForm template associated with the current step
Validate ExpressionCustom code that allows you to validate the input data
Final MessageFinal message that will be displayed by the user if the current step is set as the final  step
Create UserIndicates whether a user will be created in this step
Create Active UserIndicates whether an active user will be created in this step
Send Reset PasswordIndicates whether a password reset email will be sent to the user
Field ConfigMapping user principal fields to form template fields
User Create ExpressionCustom code that will be used to create a user
StatusIndicates whether this step is active or not.

Registration Form Creation Example

In the successive lessons we will cover the creation of a registration form that allows a user to register himself and access the support, but only to users who belong to a company registered in Deepser, this to prevent external users from opening tickets without permission.

CREATING A CUSTOM FIELD TO RECEIVE USER INPUT

Before proceeding with the actual creation of the form, we must create a custom field that allows us to receive user input.

In the following example, we will see how to create a user only if the VAT number entered will correspond to one of the companies present in Deepser. For this example,  we will assume that there is a custom field named “cust_vat_number” that will contain the VAT number of the company.

The Custom Fields will be addressed in another lesson, to go to the lesson related to the Custom Fields click here.

To create a custom field, we must go to: System -> Custom Fields.

Here we will have to click on the model “DeepRegistration – stepData”.

On the next screen, we will have to click on the “Add Field” button.

In the screen that will be displayed, will need to fill in the fields as follows:

Important is to set the “Column Type” and “Element Type” fields to text.

At this point, you will need to click on the “Save” button

Once this is done, we can proceed to implement the registration form.

Form Creation

In order to create the Registration Form we must go to the step creation menu to create a new step.

The Step Section is located under the “System-> Permissions – > user Registration -> Step” menu.

At this point, we give a name to our registration form by entering the desired name in the “Name” field

We define the “Position” field as zero.

Now we set the label that will be displayed on the registration screen by entering the desired text in the “Label” field.

Note that this field can contain text or even html with its css styles.

We define “Is Default Step” field to yes, in this way we are defining what will be the step from which the registration will begin.

Since in our example we have only one registration step, we also define “Is Final Step” to “Yes”.

Since in our example we have only one registration step we define “Next Step” as  none, in the case of a multistep registration it will be possible to set what will be the next step, through this field.

Another important thing to notice is that to populate the field, you will first need to create a new step.

We set what will be the email box that we will use to send any Password change emails through the “Mailbox” field

Now we set which form template we want to display during registration using the field “StepData  Formtemplate”

In the “Validate Expression” field, we can go to define the custom code that we will need to carry out checks on the validity of the data passed in input.

Within this field we are going to enter the following code:

				
					/**Defining Variables**/
 
//Assigning StepDatas to a variable.
$stepData = $this->getStepdata();
 
//Assigning the value og the cust_vat_number field to a variable.
$vatNumber = $stepData->getData('cust_vat_number');
 
//Assigning the value of the email field to a variable.
$email = $stepData->getData('email');
 
//if the email isn't in a valid format return an error to the user.
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
     $this->addError("Email is not in a valid format");
}
//Retriving form the user collection all the users the have the username equivalent to the ginven e-mail.
$usersCollection = Deep::getResourceModel("deep_admin/user_collection")->addFieldToFilter("username",["eq" => $email]);
//Retriving form the user collection all the StepData the have the username equivalent to the ginven e-mail.
$stepDataCollection = Deep::getResourceModel("deep_userregistration/stepdata_collection")->addFieldToFilter("email",["eq" => $email]);
 
//If uone or more user or StepDatas where found retun an error to the user.
if($usersCollection->count() || $stepDataCollection->count()){
     $this->addError("Email Already Registered");
}
 
 
/**If the company is present in Deepser we allow the registration otherwise throw an error**/
 
//Loading a company ginven the cust_piva field, if there is non company with this field this method retrive a new object.
$company = Deep::getModel("deep_company/company")->load($vatNumber,'cust_piva');
 
//If the returned object doesen't have the id or is null,return a error to the user.
if(!($company && $company->getId())){
    $this->addError("We are sorry, but only employee of our customer can register an account");
}
				
			

In the field “Final Message” we will define the message that we will give to the user once the registration has been successfully completed.

Here, we will insert the following code:

				
					<style>
    .cust__msg{
        margin-left: auto;
        margin-right: auto;
        display: flex;
        flex-direction: column;
    }
    .cust__msg > *{
        text-align: center;
        box-sizing: border-box;
        margin-left: auto;
        margin-right:auto;
        width: 100%;
    }
    .cust__msg .row{
        display: flex;
        justify-content:space-evenly;
        padding-right: 30%;
        padding-left: 30%;
    }
 
</style>
 
 
 
<div class="cust__msg">
    <h1>Success</h1>
    <p>Congratulations, your account has been created!.</p>
    <div class="row">
        <div class="col-sm-3">
            Username: 
        </div>
        <div class="col-sm-3">
            <?php echo $this->getStepdata()->getData('email');?>
        </div>
    </div>
    <div>
        <h6>We have sent you an email with the link to reset your password.</h6>
    </div>
</div>
				
			

At this point, we will have to define to create a user by defining the field “Create User” to”Yes”.

Now, we will define if the user will be an active user by defining the field “Create Active User” to “Yes”

Now we will define whether to send the user an email at the end of the procedure that will allow him to reset the password using the “Send Reset Password” field.

Now, in the “Field Config” field we will define the mapping of the user template fields with the form fields. To add a new field to map with the form data simply click the “+” button.

We have defined the users’ field as follows:

In the “User Create Expression” field, we can define custom code that will allow us to set the user’s attributes  or in general to perform actions when creating a new user. In this field, we will enter the following code:

				
					//getting the datas from the form
$stepData = $this->getStepdata();
// assigning the end user role to the created user by passing the role id
$this->getUser()->setData("role",73);
				
			

Finally, we set the “Status” field to Enabled (If it wasn’t already set to Active).

At this point, you will need to click on the button “Save” or “Apply”

Editing the form template

To modify the form template that will be displayed during registration, you will need to click the “Preview” button

At this point, you will need to click the pencil button:

And then go to the StepData tab:

Here you can enter the fields by dragging them from the right column into the grid

Finally, you will need to click on the Save Button.

Token usage

During the registration phase it may be necessary to validate the user’s email, to do this you can send a token that will allow you to verify the user’s email.

Taking as a basis the previous example, we create another step, this time ignoring the part related to the creation of the account, in addition we will configure the sending of the token.

EMAIL TEMPLATE CREATION

In order to send the verification token to the end user it will be necessary to create an email event with its associated template form that will be used by Deepser to send the email to the user who is registering.

To create a custom mail event you will need to go to the System -> Tools ->  Email -> Templatemenu.

Then you will need to click on the “Add MailTemplate” button.

In the screen that will open you will need to define a name for the template, to do  this, simply enter the desired name in the “Name” field.

Next, we will define a code for the template, filling in the “Code” field.

At this point, it will be possible to insert in the “Subject” section the php code that will compose the subject of the email.

You can use the following code as a reference to compose the subject of the email:

				
					<?php echo Deep::helper('deep_email')->__('DEEPSER - Confirm your Registration')?>
				
			

Now it will be possible to insert in the section  “Body”, that will represent the content of the message, the PHP / HTML code that will serve to generate the body of the  mail.

You can use the following code as a reference when creating the body:

				
					<?php
$username  = $this->getModel()->getEmail();
$firstname = trim($this->getModel()->getFirstname());
$lastname  = trim($this->getModel()->getLastname());
$tmpFullname = $firstname . $lastname;
$fullname = $fullanme != "" ? $tmpFullname : "user";
$url = $this->getModel()->getTokenStepUrl();
?>
<?php $this->includeTemplate("header") ?>

<!-- Start of Main Content -->
<tr style="">
<td bgcolor="#FFFFFF" align="center" style="">
<table width="100%" align="center" cellpadding="0" cellspacing="0" border="0" class="devicewidth" style="">
<tbody style="">
<!-- Start Spacer -->
<tr>
<td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
<td class="h26" height="36" style="font-size:1px; line-height:1px;">&nbsp;</td>
<td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
</tr>
<!-- End Spacer -->
<tr style="">
<td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
<td class="mktEditable content mktEditable content" id="edit_text_1" valign="middle" style="font-family:Calibri, Helvetica, sans-serif; font-size:16px; color:#505050; text-align:left; line-height:25.6px; font-weight:normal; text-transform:none;">
<p>
<br>
<?php echo Deep::helper('deep_email')->__('Dear %s',$fullname);?>,<br>
<?php echo Deep::helper('deep_email')->__('Please confirm your registration by clicking the link below'); ;?><br>
</p>
</td>
</tr>
<!-- Start Spacer -->
<tr>
<td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
<td height="30" style="font-size:1px; line-height:1px;">&nbsp;</td>
<td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
</tr>
<!-- End Spacer -->
</tbody>
</table>
</td>
</tr>
<!-- End of Main Content -->
<!-- start of Button -->
<tr style="">
<td bgcolor="#FFFFFF" align="center" class="mktEditable" id="edit_cta_button" style="">
<table width="100%" border="0" cellspacing="0" cellpadding="0">
<tbody>
<tr>
<td class="w22" width="41" style="font-size: 1px; line-height: 1px;">&nbsp;</td>
<td align="left">
<table class="button" cellpadding="0" cellspacing="0" border="0" align="left" bgcolor="#0080ff" style="-webkit-border-radius: 4px; -moz-border-radius: 4px; border-radius: 4px;">
<tbody>
<tr>
<td width="518" align="center" valign="middle" height="65">
<span style="color: #ffffff; text-decoration: none;">
<a class="mobButton mktNoTok" href="<?php echo $url ?>" style="font-family: Calibri, Helvetica, sans-serif; font-size: 16px; color: #ffffff; display: block; height: 65px; mso-line-height-rule: exactly; line-height: 65px; font-weight: normal; text-decoration: none; text-align: center!important;" target="_blank" title="Link al ticket">
<?php echo Deep::helper('deep_email')->__('Confirm the registration')?>
</a>
</span>
</td>
</tr>
</tbody>
</table> </td>
<td class="w22" width="41" style="font-size: 1px; line-height: 1px;">&nbsp;</td>
</tr>
</tbody>
</table>
</td>
</tr>
<!-- end of Button -->
<?php $this->includeTemplate("footer") ?>
				
			

And click on the “Save”  or “Apply” button:

EMAIL EVENT CREATION

To create a custom mail event, you will need to go to the “System -> Tools ->  Email -> Event” menu.

At this point, you will need to click on the “Add Event” button.

The following page will be displayed:

At this point, it will be necessary to give a name to the event by filling in the “Name” field.

We define Whether to send attachments, changing the value of the field “Send Attachments”, in our case we set it to  “No”.

Now, in the “Email Template” field, we select the template created in the previous point of this guide.

In the “Event Trigger”section, select “DeepUserregistration-StepData”  in the “Model” field

In the “Event Expression” entry.

We insert the following code :

				
					return true;

				
			

In the “To” section

We insert the following code :

				
					/**Configuring the language with local **/
$this->changeLanguage($this->getModel()->getCustLocale());
/**Getting the email from the current model**/
$this->addTo($this->getModel()->getEmail());
				
			

At this point, we can go to click the “Save” or “Apply” button

Now the event will have been saved.

ADD A NEW FORM TEMPLATE

To create a new form template, you will need to click on “Preview”.

Here, you will need to click on the button with the arrow icon.

Now you will need to click on “New Formtemplate”

In the screen that will open, you will need to enter in the field “Enter Template Name” the name of the new form template.

Next, you will need to click on “Save”.

At this point, the new form template will be created.

SET A FIELD AS REQUIRED

To create a new form template, you will need to click on “Preview”.

Here you will need to click on the button with the pencil icon.

Here you will need to go to the “Fieldset”:  “Step data”.

At this point it will be necessary to locate the field that we want to make mandatory and click on the corresponding gear icon.

In the screen that will open you will need to change the field “Required” and set it to “Yes”.

Now you will need to click on the “OK” button on the field configuration screen.

Finally, you will need to click on the “Save” button in the form configuration window.

At this point the field will be mandatory.

EDIT FORM TEMPLATE PRIORITY

Deepser evaluates form templates from the highest priority to the lowest priority form templates.

The priority of the form templates is therefore important to define which form template the user will see.

To set the priority, you will need to go to the arrow key.

Now click on the template you want to edit.

At this point, click on the button with pencil icon.

Now you will need to click on the “Edit  Rules” button and then subsequently set a value in the  priority field.

Finally, click on the “Save” button.

STEP CREATION

For this example we will use as a basis the step created in the previous lessons, in addition we will create two form template the first named “First” with the email fields, Firstname  and  Lastname and the second named “Second” with only the  Vat  Number field (cust_vat_number) created in the previous points  of lessons of this guide.

INITIAL STEP

Let’s go to the Step section and click on the “Add Step” button

In this new we are going to configure the field “Name”, in this field we will enter the name we want to give to the step.

We configure the field “Position” to 0

We configure the field The “Label”, this field will contain the  inscription  that  the user will see when he arrives at this form.

We configure the field “Is  Default  Step”  to  “Yes”.

We configure the field “Is Final Step” to “Yes”.

We configure the “Next Step” field on the step created in the previous points (User Support Registration).

We configure the field “Check token”  to  “No”.

We configure the field “Send Token”  to  “Yes”.

We set the “Token Duration”field, to an hour or at least to the time that we believe to be sufficient to perform the registration.

We configure the”Mailbox”fieldwith the exit mailbox that we will use for registraction.

We configure the “Email Event”fieldwith  the mail event created in the point above.

At this point we set the field”StepData Formtemplate” form template that we want to use in this first step, in the template form we set all the fields that must be filled in as mandatory, in this way the user will have to fill them in order to continue, you can refer to the previous topic for the configuration of the form field as mandatory  click here to go to the guide.

To create a custom form template you can follow the guide found in the previous article, click here to go to the guide.

We can configure the fields “Create  User”  and  “Create Active  User”  to  “No”.

In the “Validate Expression” field, we insert the following code to verify the form template.

				
					/**Variables Initialization**/
 
//Assigning the stepDatas to a variable.
$stepData = $this->getStepdata();
 
//Assigning the value of the email field to a variable.
$email = $stepData->getData('email');
 
/**Verifications**/
 
//if the emil isn't in a valid format return an error to the user.
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
     $this->addError("Email is not in a valid format");
}
//Retriving form the user collection all the users the have the username equiva-lent to the ginven e-mail.
$usersCollection = Deep::getResourceModel("deep_admin/user_collection")->addFieldToFilter("username",["eq" => $email]);
//Retriving form the user collection all the StepData the have the username equivalent to the ginven e-mail.
$stepDataCollection = Deep::getResourceModel("deep_userregistration/stepdata_collection")->addFieldToFilter("email",["eq" => $email]);
 
//If uone or more user or StepDatas where found retun an error to the user.
if($usersCollection->count() || $stepDataCollection->count()){
     $this->addError("Email Already Registered");
}
				
			

In this case we can leave the field “Field Config” as we are going to manage the creation of users in the last step

We can leave the”User Create Expression”field blank because we will not create users in this step.

At this point, Click on the Apply or  Save button.

In the end, the step will be saved.

FINAL REGISTRATION STEP

Let’s move now on to the final registration step.

In this step, we are going to change the”Check  Token”field by setting it to  “Yes”.

And we will configure the form template that will be associated with this template using the field “StepData  Formtemplate”.

At this point, we modify the Form Validate Expression field to perform the only validation of the “Vat  Number” (in the case of example).

				
					**Defining Variables**/
 
//Assigning StepDatas to a variable.
$stepData = $this->getStepdata();
 
//Assigning the value og the cust_vat_number field to a variable.
$vatNumber = $stepData->getData('cust_vat_number');
 
/**If the company is present in Deepser we allow the registration otherwise throw an error**/
 
//Loading a company ginven the cust_piva field, if there is non company with this field this method retrive a new object.
$company = Deep::getModel("deep_company/company")->load($vatNumber,'cust_piva');
 
//If the returned object doesen't have the id or is null,return a error to the user.
if(!($company && $company->getId())){
    $this->addError("We are sorry, but only employee of our customer can register an account");
}
				
			

Note: this form template must have a higher priority than all the others

At this point, you will need to click on the “Save” or “Apply” button.

Enabling Registration

To enable the possibility of registering through the registration form, it will be necessary to go to the System -> Configurations  -> Admin -> Security menu.

Here you will need to change the field “Enable User Registration” and set it to “Yes”.

Now, to save the changes, you will need to click on the “Save Config”button.

At this point, the registration link will have appeared on the main Login page:

LDAP Configuration

Deepser natively supports integration with the LDAP protocol.

LDAP is a protocol for centralized resource management.

Deepser’s LDAP integration allows you to easily import users and or groups containing users that you will need to be enrolled to be managed/enabled in Deepser from an existing LDAP installation.

Note that Deepser synchronizes resources with LDAP in read-only mode and can independently manage the update of states or generally modified parameters on the LDAP Resources placed in the LDAP controller, this translates into the fact that if a user is moved to group or disabled or  in general changes are made to the user on the LDAP controller the same changes,  in a standard case, will be replicated on Deepser.

CONFIGURING LDAP INTEGRATION

To configure an LDAP integration on Deepser you will need to go to the System -> Permission  -> LDAP Integration menu

In the screen that will open, you will be able to view the LDAP integrations already configured and configure new ones.

To configure a new integration, you will need to click on the Add LDAP button.

After that the following screen will open:

Below are the fields present and their meaning:

FieldDescription
Show In LoginThis field indicates whether this LDAP integration will be visible on the login page
Is DefaultIndicates whether this LDAP integration will be the one selected by default in the list on the login page
NameLDAP Integration Name
Domain ControllerThe address at which to find the domain controller.
Cron ExpressionCron expression that indicates how often the integration will be performed.
StatusIndicates whether this integration is active or not, if it is not active the synchronization will not be performed.
Base DN  Domain base name, this field indicates the point below which Deepser will have visibility in the domain forest. 
Time-outIndicates the maximum time within which if a request is not answered, the request must be considered expired.
Use SSLIndicates whether the domain controller uses S.S.L. encryption
Use TLSIndicates whether the domain controller uses T.L.S. encryption
Follow ReferralsThis field indicates whether to follow the referral links generated by the LDAP controller. Referral links are links that indicate that the server you are    querying does not directly own the requested resource, but has a reference to the server or domain that owns that resource.
Admin UsernameUsername of the user that Deepser will use to read domain’s users.
Admin PasswordPassword of the user account that Deepser will use to read access the Domain Controller.

In the Users Configuration section, you will define how users will be synchronized in Deepser.

Below are the fields in this section and their meaning:

FieldDescription
User Name AttributeIndicates which field of the response obtained from the domain controller will contain the user’s name
User RDN AttributeThis field is the field that indicates the path relative to another entity (parent) of the resource in the Domains Forest .  ES:  distinguishedname.
User Fields  This field is used to map the relation between domain user’s fields and user’s fields in Deepser
User Object FilterThis field is used to specify an LDAP query, this will serve as a filter to retrieve only users who match the search criteria.
Account PrefixAccount prefix e.g.: “EXAMPLE\<username>”. In this case “EXAMPLE\” is the account prefix.
Account SuffixAccount suffix ex: “<username>@example.local”. in this case “@example.local” is the account suffix.
Disable UsersThis field indicates whether users created on AD as disabled should be imported as disabled or not.
Custom CodeCustom code to indicate how user field values imported from integration are assigned.

In the Groups Configuration section, you will define how groups will be synchronized in Deepser.

Below is a list of the fields present and their meaning:

FieldDescription
Group EnableThis field is used to enable  the import of groups into Deepser from the forest.
Group Base DN  Indicates which is the name of the base domain in which the groups reside (e.i.: cn=exemple,  dn=com)
Group Name AttributeIndicates which field in the object returned by the request to the domain controller will contain the name of the group.
Group Members Attribute  Indicates which field in the object returned by the request to the domain controller will contain the list of users who belong to the group
Group Object FilterThis field is used to specify an LDAP query, this will serve as a filter to retrieve only the groups that match the search criteria.
Group Fields  This field is used to bind domain group fields to group fields in Deepser

Once the fields have been configured, you will need to click on the “Save” or “Apply” button.

At this point, by clicking on the “Check LDAP” button, you can check if the integration works correctly.

If the integration works correctly, a green banner will be displayed in the upper right corner of the page.

In case of error, you will see a red banner in the upper right corner of the page.

SSO Deepser Configuration

SSO (Single Sign On) is the technology that allows you to use delegated authentication to access Deepser.

In Deepser you can configure the sso using “Google” or “Azure” as the preconfigured provider.

Alternatively, you can also configure other delegated authentication providers using the Client OAuth configurations, but in this case you will need to manually configure the authentication parameters.

Configure SSO

To configure a new ss integrationor you will need to go to the System > Tools > OAuth > Client menu

Here you will need to click on the “Add Client” button:

As a first step you will need to assign a name to the client and click on the “Save” button to get the “Redirect Uri” that will be needed to configure the provider->side SSO.

After that, you can continue the configuration.

In the screen that will open you will be able to implement the configurations to implement SSO.

Below are the fields with their meaning:

Field

Description

Name

Identification name of the OAuth Client

Status

This is the status of OAuth Client, enabled or disabled

Provider

OAuth provider. This field can take 5 values: Google, Azure, Generic, Datto RMM, NinjaOne. In case this field is set to Google or Azure it will be possible to ignore the configuration of the fields: {{Insert list of fields already configured}}. If the field is configured to Generic you will need to manually specify the configuration of the fields.

Type

This field contains all the types that a provider can have. The values present depend on the selected provider.

Tenant ID

Required for Azure provisioning provider

 

Client ID

This field must be enhanced with the client id that will be provided by the Delegated Authentication provider.

Client Secret

This Field must be configured with the client secret that will be provided by the delegated authentication provider.

Scope

This field indicates the scopes to which the client will request access to the resources. This is visible only for Generic provider.

Url Authorize

Authorization url. this parameter is the endpoint to call to obtain authorization this parameter must be provided by the authentication provider. This is visible only for Generic provider.

Url Access Token

It is the ‘URL base’ to which the parameters are added to request the authentication token (post-authorization step). You do not need to compile it for Google or Azure providers, the default values will be used. This is visible only for Generic provider.

Url Resource Owner Details

Base url of the server responsible for managing resources. This parameter must be formed by the provider. This is visible only for Generic provider.

Proxy

This field, if enhanced, will use the proxy indicated to forward requests for Delegated authentication. This is visible only for Generic provider.

Verify

If you have configured a proxy you can enable or disable SSL check. You do not need to compile it for Google or Azure providers, the default values will be used. This is visible only for Generic provider.

Scope Separator Char

Scope separator character, indicates which character the provider uses to indicate the end of one scope and the beginning of another.

At this point the client verification key will be displayed, it will be necessary to click the validate button.

At the end of this configuration, you will need to click on the “Apply” button

You will then be redirected to the login screen of the Delegated authentication provider you are configuring.

At the end of the wizard if everything went well you will be redirected to the Deepser OAuth client screen with a message that will indicate that the configuration has taken place successfully.

In case of errors on the same page the error message will appear at the top.

USER TAB CONFIGURATIONS

In this tab are the configurations related with the users either in the linked provider and in Deepser

Below are all the fields available in this section:

Field

Description

Related LDAPs

You can select one or more options from Public OpenLDAP ForumSys, Public OpenLDAP Debian.

Username Attribute

Specify which user data attribute will be used to create the username.

User Data Source

Select one of the options: Endpoint or ID Token (JWT)

Endpoint User Data

Additional information for EndPoint user data source

User fields On Creation

Is a mapping between the user fields in Deepser and the related Provision. This will be used on sign up with selected Provider or when is the first time of provision for the specific user.

User Create Expression

Is a field that accepts PHP script to do the mapping between the user fields in Deepser and the related Provision. This will be used on sign up with selected provider or when is the first time of provision for the specific user.

The default variables are:
$user => user array
$oauthUser => OAuth user array

User fields On Update

Is a mapping between the user fields in Deepser and the related Provision. This will be used every time a user signs in with the selected Provider.

User Update Expression

Is a field that accepts PHP script to do the mapping between the user fields in Deepser and the related Provision This will be used every time a user signs in with the selected Provider.

The default variables are:
$user => user array
$oauthUser => OAuth user array

Login Button Disabled

Is used to hide the login button related with the selected Provider

Login Button Caption

Is used to change the text inside the login button

Login Button Icon

Is used to change the icon inside the login button

CONFIGURE PROVISIONING 

The Provisioning functionality allows you to automatically create in Deepser the users and groups registered within your Microsoft Azure environment, if the latter have been enabled for the SSO application. 

Therefore, instead of being created/updated only at each login, it is possible to perform a synchronization between the users present in Azure who must log into Deepser, and the related User records in Deepser.  

This functionality can be performed only once, by clicking on the “Provision” button at the top right (mainly used for testing the configuration), or even be scheduled to run several times a day by configuring the Cron expression. 

To configure this functionality in Deepser, in addition to what is seen in the “Configure SSO” section, within an Azure SSO client, it will be necessary to go to the “Provisioning” tab and configure the necessary parameters. 

 

Below are the fields with their meaning: 

Field 

Description 

Provisioning enabled 

If toggled on, provisioning is enabled 

Provisioning Provider 

If “Azure” is selected,  some fields will be available

Cron Expression 

If “Azure” is selected, some specific fields will appear and others will become required 

User Provisioning Mode 

You can select the way in which users will be synchronized. Required for Azure provisioning provider. 

Disable Users 

If toggled on, local user status will be updated with provisioned user status. 

Disable Deleted Users 

If enabled, if the provided user has been deleted, or does not match the filters, or is removed from the users assigned to the application, disables the relative users in Deepser. 

User Filter 

If provisioning provider is Azure, write filters in query string format, ie: 

$filter=surname eq ‘Foo’ 

$filter=jobTitle eq null 

$filter=userPrincipalName in (“Foo”,”Bar”) 

$search=”surname:Foo” 

For documentation, see Microsoft Graph documentation 

User Group Filter 

Only provision users which are members of these specific groups. 

Groups are filtered by the field specified in Group Name Attribute 

Group Name Attribute 

Specify which group data attribute will be used as the name of the group. 

It is also the name of the group attribute to filter by in the User Group Filter and in the Group Filter.If no value is provided: Azure provisioning provider, will use displayName by default. 

Group Provisioning Mode 

You can select the way in which groups will be synchronized. Required for Azure provisioning provider. 

Group Provisioning Enabled 

If toggled on, groups will also be synchronized. 

SSO Login/Provisioning Configuration – Azure

In Deepser you can set up SSO using Azure as the default provider.

This article explains how to configure Deepser and Azure, to allow SSO and User Provisioning via Azure Account in Deepser.

It includes 3 steps:

  • Oauth client creation in Deepser: In this step we can obtain a Redirect Uri for using it in the next step (Azure Configuration).
  • Azure configuration: The configuration from provider side.
  • Oauth client configuration completion in Deepser: The completion of the Oauth client created in the first step.

Note: SSO Login can be configured only on HTTPS protocol.

Deepser Oauth Client Creation

To configure a new SSO integration you will need to go to the System >Tools >OAuth >Client menu

Here you will need to click on the “Add Client” button:

As a first step you will need to assign a name to the client and click and set the following fields as follow:

Name is the name of the oauth client.
Provider you should select Azure and type as User. The Tenant ID will be populated after you finish.

Then you can click on “Apply” or “Save” button.

After the saving you can be able to copy the “Redirect URI” from the following field:

The “Redirect Uri” will be needed to configure the provider->side SSO (Azure in our case).

So, the first step of Azure SSO Configuration in Deepser is concluded. The next steps will be Azure Configuration and then the completion of the configuration in Deepser.

Azure Configuration

In this step we can manage the configuration from provider side (Azure).

You will need to login as administrator to the Azure portal: https://portal.azure.com/.

Note: We recommend performing all configurations in incognito mode or in a browser without any active logins to Azure/Outlook 365 to avoid user conflicts during the configuration.

App Registration

Search for app registrations and open it

You can proceed with a new APP Registration (API), by clicking on “New registration” button:

On App Registration we can proceed entering the following information:

  • Name for the new App,
  • Supported Account as “Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)”,
  • Redirect URI as “Web” type (Previously generated and copied from Deepser Oauth Client) [LINK TO “Deepser Oauth Client Creation” section]

In conclusion you can click on “Register” button.

App Authentication

You can now access your newly registered application and navigate to ‘Manage > Authentication’ from the menu.

From here, you can confirm that the correct Redirect URI is set under the ‘Web’ section, and enable the following tokens:

  • Access tokens (used for implicit flows)
  • ID tokens (used for implicit and hybrid flows)

App Certificate & Secret

Under “Manage > Certificates & secrets” in the menu, you can create a secret. During the configuration process, you’ll need to set its expiration time and copy its value, which will be used later to complete the configuration in Deepser.

The copied secret value will need to be entered into the field “Client Secret” on the oauth client record in Deepser:

Notes:

  • Be sure to copy the value of the secret, not the Secret ID.
  • You must copy the secret value during the creation phase, as you won’t be able to access it later (in that case, you would need to recreate it).
  • If you set an expiration for the secret, remember to renew it before the expiration date

App Token configuration

Under “Manage > Token configuration” from menu you can set the following optional claim IDs by clicking on “Add optional claim”:

  • acct
  • email
  • family_name
  • given_name

When adding the claims, remember to check the box for “Turn on the Microsoft Graph email, profile permission (required for claims to appear in the token)”:

App API permissions

Under “Manage > API permissions” in the menu, you can add the following permissions for Microsoft Graph and then run the “Grant admin consent” action:

  • email as Delegated permission
  • offline_access as Delegated permission
  • openid as Delegated permission
  • profile as Delegated permission
  • User.Read as Delegated permission

Also at this stage, if you need to Provision user/groups in Deepser, you need to add permissions for:

  • User. Read All as Application permission
  • Group. Read All as Application permission

Click on “Add a permission” to open the permission selection prompt:

Then select “Microsoft Graph” as API permission to use:

From that screen you can choose Delegate or Application permissions and use the search field for research the desired permission to add:

After adding all desired permissions, you can run Grant admin consent command:

Enterprise Application

Now you can switch to “Enterprise Applications” by searching for it in the global search:

Then search and access your new registered application clicking on it:

After access to it, go to its properties and change the following configurations:

  • “Enable for user to sign-in” to YES
  • “Assignment require” to YES

Users and Groups

To enable provisioning for users and groups in Enterprise Application you can add your desired users and groups:

Now that everything is configured in Azure, you can go back to the Oauth Client in Deepser.

Azure > Deepser Configuration

Before going back to the Oauth Client in Deepser, we can note down all the Azure information to be used in Deepser Oauth client configuration. Below is a summary of the Azure information to be reported in Deepser:

Secret Value

The “Secret value” will be entered “Client Secret” field in Deepser (“General” Tab):

Notes:

  • Be sure to copy the value of the secret, not the Secret ID.
  • You must copy the secret value during its creation phase, as you won’t be able to access it later (in that case, you would need to recreate it).

Application (client) ID

The “Application (client) ID” will be entered “Client ID” field in Deepser (“General” Tab):

Directory (tenant) ID

The “Directory (tenant) ID” will be entered “Tenant ID” field in Deepser (“Provisioning” Tab):

Deepser Oauth Client Configuration Completion

You can now return to the Deepser Oauth Client record to proceed with the completion of configuration.

Deepser – General Tab

If not already done, please configure “Provider” and “Type” field respectively as “Azure” and “User”.

Then we can proceed to set Client ID and Client Secret:

In the “Client ID” field, enter your “Azure application ID”, which you can find in the overview section of the app registration

In the “Client Secret” field, enter the value you copied earlier when creating the secret

Deepser – Users Tab

In the “Users” tab, you will need to fill the highlighted fields:

  • Username Attribute: userPrincipalName
  • Endpoint Users Data: https://graph.microsoft.com/v1.0/me
  • Users Field: to be set as shown in the image below.

In this tab you can specify field mapping between Deepser and Azure, and you can also populate other fields and perform processing in Deepser upon creating/updating a user via the User Create Expression and User Update Expression fields.

Deepser – Provisioning Tab

If you want to enable users and groups provisioning, you can do it from “Provisioning” Tab.
In the provisioning tab you will need to fill in the fields highlighted in the figure:

In the “Tenant ID” field, enter your “Azure Directory (tenant) ID”, which you can find in the overview section of the app registration (like the Client ID):

After completing the configuration, you can return on the “General” Tab, and click on the “Validate” button and check if the connection between Deepser and Azure works well.

Note: We recommend performing validation in incognito mode or in a browser without any active logins to Azure/Outlook 365 to avoid user conflicts during the configuration.

For doing this, you can copy validation URL directly from “Redirect URI” field:

By clicking the provision button, you can check the configuration, and the users/groups selected in the Azure app should now correctly imported into Deepser.

You can also configure a Cron Expression to automatically run the provisioning at scheduled times.

Also refer to this article, for a better understanding of the fields in this form.

Multi Factor

Multi-factor authentication (MFA) is a security system that requires multiple forms of verification to authenticate a user’s identity and grant access to a system. Instead of relying solely on a password, MFA typically combines something the user knows (like a password) with something they have (such as a smartphone or email address for receiving a code).This layered approach significantly enhances security by making it harder for unauthorized users to gain access, even if they obtain one factor of authentication.

Multi Factor Configuration

To go to the Multi Factor Configuration you will need to go to the

System->Tools->Multi Factor->Configuration

To create a new one you will need to Click on Add Configuration button on the top right of the screen.

The following screen will open:

Field Name

Description

Name

Name of the Configuration

Type

Type of the Multi Factor Authentication TOTP(APP) or Email

Enable Groups

Groups that will be able to use Multi Factor Authentication

Label

Configuration’s Label that will be shown on the app

Status

Enabled or Disabled. Weather the session is enabled or disabled.

Note: Both types of Multi Factor Authentication are suggested to be enabled in order to deal with unforeseen events(such as phone out of charge or unable to access email).

Enabling Email MFA in Deepser

Email MFA(Multi Factor Authentication) is possible in Deepser. In order to enable it you will have to choose the type Email in the Multi Factor Configuration.

Field Name

Description

Name

Name of the Configuration

Type

Type of the Multi Factor Authentication TOTP(APP) or Email

Enable Groups

Groups that will be able to use Multi Factor Authentication

Status

Enabled or Disabled. Weather the session is enabled or disabled.

Mailbox

The configured mailbox that will be used to send out the code via email

Mail Template

The email template that will be received via email

Token Valid Time

The time that the received code is valid for

After all of the fields are completed, whenever you try to log in the code will be sent to the email of the account.

Now every time you try to log in you will have to enter the MFA code received via email.

Depending on how you have configured the email template, this is how it will look like on the email.

In case you fail to insert the code within the chosen Token Valid Time, the following screen will appear which notifies you.

Useful guides: Out-going mailbox , Email Templates , OAuth Client for Email Integration

Enabling APP MFA in Deepser

In order to activate the MFA in deepser you will need to go to your account settings.

Afterwards you will need to go the Security tab.

To enhance security, Deepser utilizes multi-factor authentication (MFA), which integrates an additional verification step involving a secondary device, typically a mobile phone.

You can verify your identity using an authenticator app like Authy, Google Authenticator, Microsoft Authenticator. For this guide, we are going to use Authy.

Scan this QR code through the app; it will display a 6 digits code which you need to enter below to enable login by app.

Using Authy App, you will have to Add An Account and then scan the QR code shown on account settings of deepser.

After you have scanned it, you would be able to see the configuration settings you set before, which you can also change whenever you need to from deepser or through the app.

After you have saved the settings, the 6 digit code will appear on your mobile screen, which you are required to enter in the Account Security Field.

And after the correct code has been set, you have to click on Verify and the following screen will appear:

Now every time you try to log in you will have to enter the MFA code in the authentication app.

Please note that each verification code generated for Deepser’s multi-factor authentication (MFA) remains valid for 30 seconds, after which a new code is automatically generated.

Authentication Request

Each request for log in is stored and saved in Deepser. You can view it by heading to

 System->Tools->Multi Factor->Authentication Request.

Field Name

Description

User

The user that requested to log in

Session ID

Unique ID for each log in session

State

Shows if the log in was verified or not

Generated At

The date and time the request was generated

Attempts

How many times did it take for the user to set the correct authentication code

Last Attempt At

Date and Time the user last tried to log in

Last User Agent

Web Browser or Application that was most recently used to access Deepser

Last IP Address

Numerical Label of the most recent device network that was used to access Deepser

Status

Enabled or Disabled. Weather the session is enabled or disabled.

Groups

Once the Users are created, Deepser allows you to organize them into Groups.

Groups are intended as work groups of backend user (Key-User, Agent, Admin) or End-User. A user can be part of several groups.

In Deepser, through groups, you can manage two fundamental aspects: record assignment and visibility.

RECORD ASSIGNMENT

Once the group configuration is complete, records can also be assigned to groups.

For example, in the Service module, we can define the assignee group of a request.

Once the group has been selected, even the select-box with the users assigned to the record is automatically filtered according to the members of that group.

RECORDS VISIBILITY/MODIFICATION/DELETION PERMISSIONS

 Deepser allows you to filter, according to the groups to which the user belongs, the resources he can access.

It also allows you to define which permissions (visibility, modification, deletion) on records have the different teams of users within the modules they can access.

Groups Creation

To create new groups in Deepser, or manage existing ones, go to the menu item System-Permission-Groups. This menu is accessible only by Administrator role user.

At this point the main grid of the groups will be shown.

To add a new group click on the button (top right, circled in the picture) ‘+ Add Group‘.

 

At this point the group creation form will open.

The fields of the form have the following meaning

FieldMeaning
NameThe name of the group, displayed inside the select-boxes and grids in the system.
StatusIndicates whether or not the group is active in the system.
EmailThe group email (if any), to send automatic notifications to the email box dedicated to the team.
LevelThe level of support of the group. It is a useful number for Service Desk measurements and automation. For example, if you want to measure the working time of all top-level support teams, set level 1 to all top-level support groups in your organization.
Company VisibilityA user who belongs to a group with this field enhanced sees only the data of his company or sub-companies. In the case of a user with User type, this field is by-passed, because the user sees only the data of his Company.   Note: the same field is also present in the individual user form, so the system will first try to apply the setting at the user level; if it is not set, apply the setting at the group level.
DescriptionThe description of the group. Data used to keep internal notes on the configuration or meaning of the group.

Manage Users in Groups

ADD USERS TO GROUP

To add users to a group, after you’ve created it, click on the Members tab, in the group configuration form.

At this point a grid (Relation Grid) will be shown, containing all users already present in the group (if the group has just been created it will obviously be empty).

Click on the Add button to open the popup with the list of users in the system.

To add one or more users to a group simply follow these 3 steps.

  1. Select users using the checkbox on the left.
  2. Select the Add item in the Select at the top right.
  3. Click the Submit button to finish entering the system.

REMOVE USERS FROM A GROUP

To remove users from a group click on the Members tab, present in the group configuration form.

At this point a grid (Relation Grid) containing the users present in the group will be proposed.

To remove one or more users from a group simply follow these 3 steps.

  1. Select users using the checkbox on the left.
  2. Select the Delete item in the Select at the top right.
  3. Click the Submit button to finish entering the system.

Company

In Deepser companies are important to manage visibility as users with the exception of empowered Users will be able to see only tickets, there but more generally all entities only if they are assigned or belonging to the company of which they are part.

In Case a user is a business supervisor and he is assigned to the Additional companies he will see all the entities belonging or assigned to the Additional Companies.

Users whose company is the parent of other companies, think for example of a company that is the parent company, will be able to see the entities connected or belonging to the daughter companies if and only if the “Limit to Company Data” field is not configured in the user’s configuration to “Company Data”.

Companies in Deepser

As mentioned in the introductory article of this lesson, companies have an important role in managing visibility.

In this article, we will analyze in the Deepser entities the ways in which the Corresponding Companies are associated.

THE CI

Companies in Deepser can be both assignees of a ci and owners of a ci.

If the company is assignees of a ci (figure 1) then it means that the users of that company or of the subsidiary companies will be able to see and interact with that ci  (place  there is no limitation of visibility for groups defined at the level of cmdb).

If the company owns a ci (Figure 2), users of that company will be able to see and interact with the ci in question.

Note that the visibility of the ci is evaluated in “or“ between the owner companies and the assignee companies

Tickets

Companies play a fundamental role in ticket management as  they are evaluated by Deepser to determine which tickets will be viewed by a  given  user (End User), however if  the  user in question is not a  Company  Supervisor or an Empowered User  and is an End User, it will only see the tickets created by him, also Agents, Key Users and even Administrators could be limited to view the company datas, in this case they will see only the tickets created by their company in the user portal and in the backend.

Contacts and CRM items

In Deepser you can associate a company with an account in the CRM, or create a company from a CRM account.

The Accounts in the CRM serve as an address book and allow you to enter contact information related to the company.

Contracts

In Deepser it is possible to create contracts and associate them with a company, it can be  the owner (Fig. 1) or  assignee of the contract  (Fig. 2), in this way it will be possible to automatically manage the costs  related  to a supplier company  or the costs related to the assistance lines, for example it is possible to automatically manage the total number of hours of assistance and the total number of hours spent by a customer company.

For a more in-depth analysis of the contracts in Deepser  please check  the corresponding section of the documentation; to go to the corresponding section  click here.

Company Creation

In Deepser you can create new companies by going to the menu: System -> Companies.

Here you can create a new company using the “Add Company” button

At this point, the following screen will open:

Below is the list of fields and their meaning:

FieldDescription
Parent AccountThis field indicates which is the parent company of the company that is  configured, if the  company will not have any parents then you will need to set the field as empty.
NameName of the company you are configuring
DescriptionDescription of the company you are configuring
PhonePhone of the company you are configuring
FaxFax of the company you are configuring
AddressAddress of the company you are configuring
CityCity of the company you are configuring
AreStatus (geographical/political) of the company you are configuring
CountryCountry of the company you are configuring
Zip CodePostal Code of the company you are configuring
NotesNotes about the company you are configuring
Email DomainsEmail domains associated with the company. Through this field it is possible to associate one or more email domains so that if one never, is received from one of these domains it is associated with the correct company.
LogoLogo of the company you are configuring
Primary ContactUser who will be used as primary contact by Deepser, this will be the reference user  for this company
StatusIndicates if the company is active or not, if it is not active it will not be displayed among the possible choices in the Company comboboxes.

At this point, it will be sufficient to click on the “Save” or “Apply” button to save the changes and create the company.

Parent Companies

Parent Companies in Deepser are companies that are referred to as relatives in related companies and that do not have a parent company themselves.

Companies’ Supervisor users who belong to the parent company if not limited to viewing only company data will also have visibility on the entities that belong or are assigned to the subsidiaries.

A company can have only one parent company, while a parent company can have several subsidiaries companies.

Creating a parent company

To make a company a parent company, you will need to go to the System -> Companies menu.

At this point, we must enter into the modification of a company that will become a subsidiaries company.

At this point it will be necessary to modify the “Parent Account” field, here we will select the company that will become the parent company.

At this point, you will need to click on the “Save” or “Apply” button

Now the company will be saved.

Email Domains

In Deepser you can associate a domain with a company.

In this way, when Deepser receives an email from an unregistered user but with a domain associated with a company, Deepser will associate automatically that email with the correct company.

ADD AN EMAIL DOMAIN TO A COMPANY

To add an email domain, you will need to go to the menu: System -> Company

At this point, we click on the company to which we want to associate the domain or domains.

 

To this point we go to the “Email Domains” field, here we click on the “+” button.

In the text field that will appear we enter the domain in the form: “domainname.ext” for example: “example.com”.

Now is possible to proceed in the same way for all the domains that we want to associate with this company.

Once finished, you will need to click on the “Save” or “Apply” button.

In the company will be saved, and the emails received from these domains will be associated with the company.

Sync Account CRM Companies

In Deepser you can create a company starting from an account on the CRM.

This allows you to automatically transform also reporting the data entered in the account in the company model.

Note, however, that not all fields are synchronized automatically, for example the custom fields are not natively reported, to overcome this you can define an advanced synchronization procedure that we will deal with in the next topic.

SYNCHRONIZE CRM ACCOUNT WITH COMPANY

To synchronize a CRM Account with a company, you will need to go to the CRM -> Account entry.

Here, you will need to click on the Account you want to turn into a Company.

In the screen that will open, you will need to click on the “Sync Company” button located in the upper right corner.

In the popup that will open you will have to be asked if you are sure to proceed, you will need to click on the “Yes” button to create the company or on the “Cancel” button to cancel the operation.

At this point, the new company will be created.

Note that if there is already a company with the same name as the Account it will not be associated with the existing company, but another one will be created associated with this crm account.

Advanced Sync

In Deepser it is possible to configure an advanced Synchronization procedure that allows you to set  in the created company the  fields  that the Standard synchronization process would not import  (e.g.  custom fields).  

In this guide we will see how to implement this procedure through custom events, we will see the creation of a unilateral synchronization procedure that is, the updates will be implemented by taking the changes from the CRM accounts and transporting them to the companies.

Note that advanced synchronization is an extension of the synchronization process and onventional, not a substitute for it,   so before the changes implemented in this guide take effect you will need to carry out the conventional synchronization process.

Creating a custom field

Before proceeding with the actual creation of the form, we must create a custom field that allows us to receive user input.

For custom fields will be addressed in a special lesson, to go to the lesson related to custom fields click here.

To create a custom field we must go to: System -> Custom Fields.

Here we will have to click on the desired model, in our example “DeepCrm – Account”.  

On the next screen we will have to click on the “Add Field” button

On the next screen you will need to fill in the fields as follows:

Important to set the “Column Type” to text and the “Element Type” to text.

At this point you will need to click on the “Save” button

Once this is done we can proceed to implement the real registration form.

ADVANCED ACCOUNT TO COMPANY SYNC EXAMPLE

In the following example we assume that there is both on the model “DeepCrm – Account” and on the model “DeepCompany – Company” a custom field of type text containing the VAT  number.

The field on the model “DeepCompany – Company” named  ” cust_vat_number “.
The field on the model “DeepCrm – Account” named “cust_vat_number”. 
Logically it is possible to define any field following this example as a starting point.

To implement create a custom event for advanced synchronization you will need to go to  the menu: System- > Custom Fields.

Here you will need to go click on the “DeepCrm Account” template.

At this point it will be necessary to click on the “Events” item.

In the screen that will open you will need to click on the “Add Event”button.

Now the following screen will open:

Here we are going to fill in the “Name” field with the name we want to assign to the event.

We set the Type field to “After Save”.

Now fill in the “Method” field with the following code:

				
					/** Verify if the account is synched**/
if($this->getSynced() && $this->getCompanyId()){
    /**Load the company from given the company id**/
    $linkedCompany = Deep::getModel('deep_company/company')->load($this->getCompanyId());
    /**If the company exist and the company have an id set, set the sync data, otherwise, do nothing**/
    if($linkedCompany && $linkedCompany->getId()){
        /**Load the custom field from the Account and insert it in to the company**/
        $linkedCompany->setData("cust_vat_number",$this->getData('cust_vat_number'));
        /**After the valorization of all the fields call the method Save on the company object to update the ditas on the Database**/
        $linkedCompany->save();
    }
}
				
			

Finally, must click on the “Save Event” button or the “Save And Continue  Edit” button.

Now when we are going to sync  a company he custom fields that we have indicated will be synchronized.

Visibility management in Deepser

In Deepser visibilities are managed through 4 main elements:  The “Requester” field, Roles, Companies and Groups.

Below, we will cover each of these aspects in more detail.

THE REQUESTER FIELD

The requesting field indicates who requested the Ticket, this field is used by Deepser to set the visibility of the Tickets for the End Users, unless the user is a Company Supervisor or an Empowered User.

ROLES

In Deepser, roles are used to define which resources the user will have access to.

We can exemplify the concept of managed roles with vertical visibility in Deepser, that is, the visibility of the modules presented in the sidebar

THE MAIN ROLES IN DEEPSER AND THE PREDEFINED ROLES

The default roles in Deepser are:

Role Description
Administrator Users administrators in Deepser, they have global access and bypass the limits of visibility in the backend, in addition to this they faculty to modify the grids and form templates. This is the only role that has access to the system configuration and the System tab). Note: Super Admin users are Administrators who have set “All” in the resource visibility section. This role is the only one that has access to scripting areas in Deepser.
Agents These Users have the right to modify the grids and form templates, but they do not have access to the scripting areas or even to the modules placed in the System tab. For the rest by default they have global access to all other modules.
Key Users These users are comparable to Agents users, but unlike them, they have no ability to modify any system configuration, including grids and form templates.
Users These are the end users, by default, these users do not have access to the backend, but only to the end user portal. Since they do not have access to the backend they cannot change any system configuration or even see the tickets that have not been opened by them. If there is a need for an end user to see tickets not opened by himself it can be modified by setting it as a Company Supervisor, in this case the user will be able to see all the tickets that belong to his company. Alternatively you can configure the user as an empowered user, this will give him visibility even on tickets not belonging to his company.

COMPANIES

At Deepser, companies are very important for managing visibility.

In Deepser a company represents a company in reality, or it can represent a department (in the case for example of a very large and structured company).

Companies limit the visibility of tickets or entities to the extent that entities created and by a company are generally only visible to users of that company or users who have that company among the additional companies.

All users who try to open a ticket or generally interact with an entity that does not belong to their company would get the “Access Denied” error.

GROUPS

Groups in Deepser allow you to manage entity visibility for groups of users.

For each Deepser entity, it will be possible to define which groups will have visibility on that resource. For all other groups, it will not be visible.

It is also important to note that in addition to groups it is possible to specify on the resource also the pseudo group “All Groups”, as the name suggests this group makes the resource visible to all groups.

If a user belongs to multiple groups, one of which has visibility and one of which does not have it, then the resource will be visible.

Permission and Visibility Handling

VISIBILITY MANAGEMENT

In Deepser it is possible to manage the user visibilit on the entities through two additional systems: Roles and Groups.

The Roles allow you to manage visibility vertically, preventing the access access to entire modules (Service, CMDB, CRM etc.) or areas (System submenu) of Deepser.

The Groups instead allow to manage the visibility in a horizontally.

On them is based the visibility, for example, of:

  • Types of Service
  • Visibility of individual Operations (through group rules)
  • CMDB classes
  • Types of Contacts
  • Any standard grid in Deepser
  • Visibility or possibility to modify fields in Form Templates
  • Email Notifications (notifications to entire groups)

PERMISSION MANAGEMENT

You can configure specific rules for each group to manage the permissions that users have on Deepser entities.

The Permissions on which the rules can be defined are the following:

PermissionExplanation
CREATEIndicates whether the user can create records for a given entity. Normally, the conditions in this case are simply true or false or indicate whether a user can create that record.
READIndicates whether the user can view the details of records for a given entity. In this case, you can define custom expressions to filter visibility on certain record types. For example, we can define that users in a group can display Service Operations, but only those of a certain Service Type. Or we can define the scenario where a user group can only display the Service Operations assigned to the users in the group.
UPDATEIndicates whether the user can edit records for a given entity. In this case, you can define custom expressions to filter the change for certain record types. For example, we can define that users in a group can modify Service Operations, but only those of a certain Service Type. Or we can define that a user group can modify only the Service Operations assigned to the users in the group.
DELETEIndicates whether the user can delete (physically delete) records for a given entity. In this case, you can define custom expressions to filter the deletion for certain record types. For example, we can define that users in a group can delete Service Operations, but only those of a certain Service Type. Or we can define that a user group can only delete the Service Operations assigned to the users in the group.
GRIDIndicates whether the user can view records, in the grids, for a given entity. In this case, you can define custom expressions to filter the display for certain record types. For example, we can define that the users of a group can display in the grids only the Service Operations assigned to the users of the group. With this permission you can filter “upstream” the queries made by Deepser’s grids, filtering them for each specific user group and separating the visibility of your service records for individual teams.

To configure permissions from the group configuration menu access the Rules tab.

A list of any rules already configured for that group will appear.

From here you can add new rules or remove already defined ones.

By clicking on the + button the form for adding a new rule will appear.

The form fields have the following meaning

FieldMeaning
ModelModel on which to define a rule/permit.
TypeType of permission for which define the rule: Create, Read, Update, Delete, Grid.
ExpressionPHP scripting area where you can define the rule by code.
AllThis option enables permission (Type), to all members of the current group, on all model entities.
Assigned to UserThis option enables permission (Type), to all members of the current group, on all entities of the model (Model), of which the User is the Assignee User.
Assigned to User GroupsThis option enables permission (Type), to all members of the current group, on all entities of the model (Model), which have the current group as the Assignee group.
User is RequesterThis option enables permission (Type), to all members of the current group, on all entities of the model (Model), of which the User is the Applicant.

Note1: if a group has no rules configured for some models then that group has read / display / write / delete privileges on all records of those models. For this reason it is always good to set the permissions within the groups whose privileges you want to restrict.

Note2: If a user belongs to several groups, which have different rules, the most restrictive one is applied, case by case.

Groups and Rules Definition

It is possible to define using PHP code, rules for the management of permissions, from the simplest to the most articulated.

Once positioned in the Rules configuration form, expand the scripting area by clicking on the </> icon G Expression field.

Inside that you can define a rule using PHP code.

EXAMPLE – DEFINE A SET OF CUSTOM RULES FOR A GROUP

In this example you want a group of users to be able:

  • Create Service Operations;
  • Delete only the Service Operations assigned to your user (Assigned To);
  • Modify Service Operations sent by a specific user group;
  • View details only of the Service Operations assigned to your Assigned Group;
  • Display in the grids only the Service Operations assigned to your user groups (Assigned Group).

To accomplish this requirements, you need to define 5 distinct rules.

RULE 1: MANAGE CREATION

To allow users to “CreateService Operations” it is necessary to define a rule having Create Type, DeepService-Operations Model and than insert the following PHP code:

				
					return true;
				
			

RULE 2: MANAGE CANCELLATION

To allow users to “Delete only the Service Operations assigned to their user” it is necessary to define a rule on the DeepService-Operations Model withType Delete where verify the current user is also the assigned user of the operation.

To do this, insert the following code:

				
					//retrieve the assigned user username
$assignedUsername = $model->getAssignedUsername();
//retrieve the current user
$currentUser = Deep::helper('deep_admin')->getCurrentUser();
//ticket has an assigned user and assigned user is the current user then allow delete action
if ($assignedUsername && $assignedUsername == $currentUser->getUsername())
    return true;
 
return false;
				
			

RULE 3: MANAGE EDITING

To allow users in the group to “Modify Service Operations sent by a specific user group” it is necessary to define a rule on the DeepService-Operations with Update Type to verify that the Requester of an operation is a member of a specific group.

To do this, insert the following code:

				
					//retrieve the requeter user obkject instance
$requester = $model->getRequesterUser();
//if requester user is member of customers group then allow the update action
if ($requester && $requester->isInGroup('Customers'))
    return true;
 
return false;
				
			

RULE 4: MANAGE THE DISPLAY

To allow users to “View details only of the Service Operations assigned to their own user groupsyou need to define a rule on the DeepService-Operations Model of Type Read to verify that the current user belongs to the assigned group.

To do this, insert the following code:

				
					//retrieve the assigned group id
$assignedGroup = $model->getAssignedGroupId();
//retrieve the current user
$currentUser = Deep::helper('deep_admin')->getCurrentUser();
// if the current user is a member of the assigned group then allow to view operation details
if ($assignedGroup && $currentUser->isInGroup((int)$assignedGroup))
    return true;
 
return false;
				
			

RULE 5: MANAGE THE DISPLAY IN GRIDS

In order to allow the users to “Display in the grids only the Service Operations assigned to the groups of which the members are member of” you need to define a rule on the DeepService-Operations Model of Grid Type to verify that the current user belongs to the assigned group.

In this case, acting on the grid, add a filter to the query that retrieve records from the database.

				
					//retrieve the assigned user
$currentUser = Deep::helper('deep_admin')->getCurrentUser();
//add a filter to the DB query on assigned group
// assigned group must be in the array returned by $currentUser->getGroupIds()
$collection->addFieldToFilter(
    'assigned_group_id', ['in' => $currentUser->getGroupIds()]
);
				
			

End Users Visibility Overview

In Deepser, end users correspond to those users whose role is configured as users.

They have access only to the user portal and possibly, if enabled, to the public portal, only if enabled.

TICKETS

End users can see only the tickets opened by them, unless they are Company Supervisors or Empowered Users.

In the case of an End user who is also a Company Supervisor, he will have access to all the tickets of his Company and all the tickets of the Additional Companies unless the user is limited to the Company Data, in this case he will have access only to his Company Ticket.

CIs

End users can view the CI assigned to them or of which they are the owners and which they belong, in the case of Corporate supervisor users they will view all the CI of their company.

FORMS

End users do not have the right to modify form fields or change the form currently displayed.

Entities Portal Visibility

For the management of modules related to the End-User Portal, it is possible to intervene through configuration to change the display/management of the modules directly from the “Configuration” section of the “System” menu:

By clicking on “Portal Configurations” you will be able to manage the following modules:

Activity – Worklog visibility

For the visibility of the Activity module in the Deepser user portal, it is possible to act by configuration by going to “SYSTEM > Configuration > Portal – Configurations” and finally Activity, we will access the Deepser section dedicated to configuring the visibility of the Activity module on the portal side:

Inside we will find the following configurable fields:

  • Show Worklogs: Which allows you to view worklog records on the end-user portal side.
  • Add/Edit Worklogs: Which allows end users to edit or add new worklogs.

 

Worklog visibility is based on the entity it relates to. If the user has visibility for that specific entity then he can also see the worklogs if added to the form template.

 

CMDB – CIs Visibility

For the visibility of CIs in the Deepser user portal, we can act in different ways.

First of all, going to “SYSTEM > Configuration > Portal – Configurations” and finally CMDB, we will access the section of Deepser dedicated to configuring the visibility of the CMDB on the portal side:

From here we can act on the configuration:

Enable: Allows you to enable or disable the visibility of the CMDB on the portal side.

Enable Priority: Allows you to choose how you want to manage the visibility of your CIs on the portal side.
The selectable values will be:

  • Global: Which allows the CMDB module to be displayed to all end users without distinction.
  • Users: Which allows the CMDB module to be displayed only to end users who have the “Portal CMDB Visibility” field set to “Yes” in their master data (accessible from System > Permissions > Users).

Once the CMDB module display type has been enabled and configured, the display of individual CI records will be managed based on the following fields:

  • Owner Company – if the company of the user is the owner company
  • Owner Group – if the user is part of the owner group
  • Assigned User – if the user is assigned user for that entity
  • Status – if the status of the entity is active

CRM – CRM Modules Visibility

For the visibility of CRM modules in the Deepser user portal, it is possible to act by configuring by going to “SYSTEM > Configuration > Portal – Configurations” and finally CRM, we will access the Deepser section dedicated to configuring the visibility of the CRM on the portal side:

From here it will be possible to indicate which modules in the CRM section must be made visible on the portal side (Enable Account, Enable Contact, Enable Opportunities fields).

You can also specify which groups will be able to access these modules, or whether all users will be able to access them indiscriminately (by selecting All groups).

 

Once the CRM forms section is enabled and configured, the display of individual records will be managed according to the “Portal Visibility” field in the reference form. Then the records will be displayed respecting the value of the following fields:

 

  • Portal Visibility = Yes
  • Linked Company – if the user company is the same as the linked company of the entity
  • Parent Company – if the user company is the same as the partner company of the entity
  • Owner User – if the user is the owner of the entity

Knowledge Base Visibility

For the visibility of the Knowledge Base in the Deepser user portal, it is possible to act by configuration by going to “SYSTEM > Configuration > Portal – Configurations” and finally Knowledge Base, we will access the Deepser section dedicated to configuring the visibility of the Knowledge Base module on the portal side:

Once the KB module view is enabled and configured, the display of individual records will be managed according to the “Portal Visibility” and “Kb Group View” fields present in the Knowledge Base record configuration:

In addition, it is possible to intervene on the visibility of a single article in the KB always through the “Portal Visibility” field present within the article:

If the “Portal Visibility” field is set to “Yes”, the knowledge base or article will be displayed on the portal side.

Password Visibility

For the visibility of CRM modules in the Deepser user portal, it is possible to act through configuration by going to “SYSTEM > Configuration > Portal – Configurations” and finally Password, we will access the Deepser section dedicated to configuring the visibility of Passwords on the portal side:

From here it will be possible to enable the display of the Password module on the portal side through the “Enable” field.

You can also specify which groups will be able to access these forms or whether all users will be able to access them indiscriminately (by selecting All Groups) via the “Enabled Groups” field.

 

Once the Password module is enabled and configured, the display of individual records will be managed based on the following fields:

 

  • View Groups – if user is part of the group he can only see and not edit the entity
  • View and Edit Groups – if user is part of the group he can see and edit the entity
  • Use Groups – if user is part of the group, he can use the password if provided in other entity like field.
  • View User – if the user is selected, he can only see the entity
  • View and Edit User – if the user is selected, he can see and edit the entity
  • Use User – if the user is selected, he can use the password if provided in other entity like field.
  • Company – if user’s company is selected, he can see the entity

Anyway, an end-user can only save private passwords. So, all passwords saved from end-user portal couldn’t be visible in the backend, but there are available only for him.

Approval Visibility

For the visibility of approvals, in the Deepser user portal it is possible to act by configuration by going to “SYSTEM > Configuration > Portal – Configurations” and finally Approval, we will access the Deepser section dedicated to configuring the visibility of the Approval module:

Inside we will find the “Enable” field as configurable. If enabled, it will allow the use of portal-side approvals.

 

However, a requirement for using portal-side approvals is the use of end-user Empowered licenses.

Only these types of users will have the ability to use the approvals module.

Survey Visibility

For the visibility of Surveys, in the Deepser user portal it is possible to act by configuration by going to “SYSTEM > Configuration > Portal – Configurations” and finally Survey, we will access the Deepser section dedicated to configuring the visibility of the Survey module:

Inside we will find the following configurable fields:

  • Enable: Which allows you to view portal-side survey records.
  • Enabled Groups: If the module is enabled via the “Enable” field, through this field it is possible to enable the visibility of the surveys to selected groups (or to all users by selecting “All Groups”).

The visibility of a single survey on the portal side will be managed based on the enhancement of the “Users” and “Groups” fields present within the survey.

Task Visibility

For the visibility of the Activity module in the Deepser user portal, it is possible to act by configuring it by going to “SYSTEM > Configuration > Portal – Configurations” and finally Tasks, we will access the Deepser section dedicated to configuring the visibility of the Task module on the portal side:

Inside we will find the following configurable fields:

  • Enable: Which allows you to view portal-side task type records.
  • Enabled Groups: If the module is enabled via the “Enable” field, through this field it is possible to enable the visibility of the tasks to the selected groups (or to all users by selecting “All Groups”.

The visibility of the tasks will instead be based on the “Portal Visibility” field present within the task and which must be set to “Yes” to make the portal task visible and the related “Assigned User” and “Assigned Groups” fields to be enhanced according to the users or user to whom the task is to be visible.

Project Visibility

For the visibility of the tasks of the project module, in the Deepser user portal it is possible to act by configuration by going to “SYSTEM > Configuration > Portal – Configurations” and finally Project, we will access the Deepser section dedicated to configuring the visibility of project tasks on the portal side:

Inside we will find the following configurable fields:

  • Enable: Which allows you to view portal-side task type records.
  • Enabled Groups: If the module is enabled via the “Enable” field, through this field it is possible to enable the visibility of the tasks to the selected groups (or to all users by selecting “All Groups”.

 

The visibility of the tasks will instead be based on the “Portal Visibility” field present within the task and which must be set to “Yes” to make the portal task visible and the related “Assigned User” and “Assigned Groups” fields to be enhanced according to the users or user to whom the task is to be visible.

Empowered End User (EEU)

An EEU (Empowered End User) is a licensed user who has access to specific features on the End User Portal, such as:

  • Approval workflows
  • Advanced data visibility.

The license type in this case is different from the license for backend users of Deepser, as it can only be used for End Users who therefore have access solely to the customer portal.

You can check the available and active licenses directly from the main users’ screen in the Backend (System > Permissions > Users):

Setting an end user as empowered, can be done by setting to “Yes” the “Empowered” field on the User model formtemplate. The “Empowered” field is visible for User model with role of “End User“.

NOTE: You can set it to “Yes” only if you have the EEU license type available. Additionally, it can only be set for users with the “Users” (End User) role.

EEU – Approvals

The Empowered End User can approve or refuse an approval process. As an EEU all the approvals will be visible through the user menu in the End Users portal.

After clicking “My Approvals” EEU will be able to see the approvals grid assigned to them.

You can find more details on how to use the Approval flow by referring to the dedicated article here.

EEU – Access Users and Groups

When a user is configured as ‘Empowered,’ they gain expanded visibility access for operations and other models, in addition to the approval flow. This is achieved through the Access Users and Groups fields, which are available by default in the Operation model and allow for more granular control over user permissions and data visibility.

  • Access User: By using this field in an operation, you can grant each individual EEU access to specific entities, such as operations. Once access is granted, the EEU will be able to view the ticket through the end-user portal.
  • Access Group: Like the Access User field, when populated within an operation, it allows you to extend the visibility of an entity if the user who is part of the group is of the “Empowered” type.

    You can find more details on how to use the Access User and Access Groups fields by referring to the dedicated article.

Company Supervisors

Company supervisors are end users who have visibility on all tickets of their company, thus bypassing the limitation of visibility regarding only the tickets requested by them.

Users can be created as Company Supervisors from the beginning, or they can be promoted later.

Below we will explain the procedure for promoting a user to a Company supervisor, to create a user from the beginning please refer to the guide regarding the creation of a user.

PROMOTE A USER TO COMPANY SUPERVISOR

To promote a user to a company supervisor, you will need to go to the System -> Permissions -> Users menu

From here, it will now be possible to access the users’ editing by clicking on an existing user.

In the screen that will open select “Is Supervisor” and set the value from “No”

to “Company Supervisor”

At this point, click on the “Apply” button or on the “Save” button

Finally, the modified user will be a Company Supervisor.

Additional Companies

Additional Companies are companies with which a user can be associated in addition to his principal company, to have visibility also on the tickets generated by these additional companies and to open tickets on behalf of third parties, in the event that he is a company supervisor.

If the user is not a company supervisor, he will be limited to seeing only the tickets assigned to him, but in the form templates where the company field is present, he can select either his company or one of the Additional  Companies.

ADDING AN ADDITIONAL COMPANY TO A USER

To add an Additional Company to a user you will need to go to the System  ->  Permissions  -> Users menu.

At this point it will be necessary to click on the user we are interested in editing.

Once we have entered the modification of the user to whom we are interested in adding the additional company, we identify the “Additional Companies” field in the template form.

 

At this point, we click on the field and start writing the name of the company to filter the field.

In this case, the company will be “Acme International”

Once you have identified the desired company, simply click on it to confirm.

The result will be as follows:

Now you will need to click the “Apply” button or the “Save” button to confirm the changes.

At this point, the changes will be applied correctly to the user.

Access Groups

You can also extend ticket visibility by using the “Access Groups” field for portal end users.

To use this field, it will be necessary to include it in the operations form as it is not normally displayed:

The field in question, in fact, through the multiple insertion of 1 or more groups, allows a ticket to be displayed even to groups of users who normally do not have visibility.

On the portal side, the standard display of information is based on the “Requester” field or on the company to which they belong in the case of supervisor users. This field gives you the option to extend the view.

However, to use this feature you must comply with the following rules:

  1. If you want to give the visibility of a ticket on the portal side to an end user, the latter must have an “Empowered End User” license and therefore must have the “Empowered” flag within his user database.
  2. For a ticket to be visible on the portal side, the user group must have visibility of the type of service linked to the ticket (via the “Portal User Groups” field in the configuration of service types).

Access Users

You can also extend ticket visibility by using the “Access Users” field for portal end users.

To use this field, it will be necessary to include it in the operations form as it is not normally displayed:

The field in question, in fact, through the multiple entries of 1 or more users, allows you to display a ticket even to users who normally do not have visibility.

On the portal side, the standard display of information is based on the “Requester” field or on the company to which they belong in the case of supervisor users. This field gives you the option to extend the view.

However, to use this feature you must comply with the following rules:

  1. If you want to give the visibility of a ticket on the portal side to an end user, the latter must have an “Empowered End User” license and therefore must have the “Empowered” flag within his user database.
  2. For a ticket to be visible on the portal side, the user must be part of a group that has visibility of the type of service linked to the ticket (via the “Portal User Groups” field in the configuration of the types of service).

Activity, Worklogs & Comments


This Course covers everything related to Deepser Activities, which is a comprensive term for Comments and Worklogs. You will learn everything related to Activities usage and advanced System Configuration.

DeepActivity Comments

With the term Activity, Deepser refers to some activities that can be done on tickets.

There are two types of activity, Comments and Work Activities, both of which are available, if configured, either in the Backend or in the Users portal.

Activities are a great way to track relevant information and communication regarding a ticket. They facilitate ticket resolution by providing an additional point of contact between operators and end users.

Comments are used in ticketing to connect users and groups related to the ticket itself. Through comments it is possible to communicate updates, useful information to close the ticket, or put in contact end users with operators.

Placing a comment

This guide will explain how to place a comment on an Operation.

1 – It is possible to access the “Activities” section of Operations through the User Portal or Backend, if properly configured.

1a – Through the User Portal, simply select the Operation on which you want to add a comment from the right grid.

1b -Through the Backend it is necessary to open the Service module through the drop-down menu, and click All to visualize all the Operations. Finally open the Operation on which you want to add a comment.

2 – At this point, scroll down to the Activity section, here comments and Work Activity are visible, the Comments tab will already be highlighted by default.

 

2 – To add a comment, click on Add Comment

3 – The form for inserting a comment is shown below

The meaning of the fields is the following:

CampMeaning
Visible on PortalSpecifies whether the comment should be visible in the user portal, thus to end users.
Created ByIndicates the creator of the comment, it is automatically filled with the current user who is commenting.
DescriptionThe text of the comment, formatted with images and structures such as tables, etc.
Comment AttachmentsAllows to attach files to the comment. Note: The files will not appear as ticket attachments, but only to the comment.

4 – To save the comment, simply click on the green checkmark in the upper right corner.

5 – The comment will then be displayed under the ticket

Comments System Configuration

For comments, it is possible to make advanced system configurations, to set options such as: in which temporal order to display comments, and to automate the change of status of an Operation when a comment is inserted.

These configurations are available in Deepser’s system configuration menu. To access in system configuration, you need to use Deepser’s backend dropdown menu, then System->Configuration->Activity->Configurations.

This is the section dedicated to the configuration of comments at system level

The meaning of the fields is the following:

SectionCampMeaning
Order CommentsComment order direction (creation date Asc/Desc)Allows you to sort comments from least to most recent (Asc), or from most recent to least recent (Desc).
Changes Service Operations status when adding a CommentEnabledIf set to yes, when a comment is added to a Service Operation, it will automatically change state if it meets some rules defined by the fields below.
 Select New Status Indicates the state in which the commented Operation is to change. For example, Taken over.
 Exclude Status Operations in any state shown in this list will not be affected by this automatism. For example, if you only want to change Operations to New status, enter all other statuses in this field.
 Apply if Created By user is in Group Allows to enable this automatism only to users member of some groups.
For example, if the status change has to occur only when an operator enters a comment, select a group of Operators.
Save Config Allows you to save the current configuration.

DeepActivity Worklog

With the term Activity, Deepser refers to some activities that can be done on tickets.

There are two types of activity, Comments and WorkLogs, both of which are available, if configured, either in the Backend or in the Users portal.

Activities are a great way to track relevant information and communication regarding a ticket. They facilitate ticket resolution by providing an additional point of contact between operators and end users.

WORKLOGS

WorkLogs are a useful tool for tracking each individual activity performed to bring the ticket to closure. WorkLogs can also be used in reporting to provide a cumulative calculation of the total work hours per user, performed on a ticket.

Entering a Worklog

This guide will explain how to create a WorkLog for an Operation.

1 – It is possible to access the “Activities” section of Operations through the User Portal or Backend, if properly configured.

1a – Through the User Portal, simply select the Operation on which you want to add a comment, from the right grid.

1b – Through the Backend it is necessary to open the Service module through the drop-down menu, and select All to visualize all the Operations. Finally open the Operation on which you want to add a WorkLog.

2 – At this point, scroll down to the Activity section, where comments and Work Activities are visible, and select the WorkLog tab.

2 – To add a WorkLog, click on Add Activity.

3 – The form for inserting a WorkLog is shown below

The meaning of the fields is as follows:

FieldsMeaning
Started AtIndicates the day and time when this activity began
StatusIndicates the status of the Activity
DurationIndicates the duration in hours and minutes of the activity , this parameter can be used in reporting to calculate the total working hours.
DescriptionThe text with the description of the work activity, formatted with images and structures such as tables, etc.
Created ByIndicates the creator of the activity , it is automatically filled with the current user who is entering it.

4 – To save the work activity, simply click on the green checkmark in the upper right corner.

5 – The result is as follows

Enabling Worklogs in the User Portal

To display WorkLogs  in the User Portal, so that end users also have access to them, you need to make some system configurations.

These configurations are available in Deepser’s system configuration menu.

To access system configuration, you need to use Deepser’s backend dropdown menu, then System->Configuration->Portal->Configurations.

This is the section dedicated to the system configuration of WorkLogs 

The meaning of the fields is the following:

CampMeaning
Show WorklogMakes worklogs visible in the user portal. The worklogs will be read-only, if ‘Add/Edit Worklog’ is set to No.
Add/Edit WorklogGives End Users the ability to insert worklogs, or modify those already present in tickets.
Save ConfigAllows to save the configuration

Worklog Global Grid

The global grid of work activities is a configurable grid that allows you to view all work activities. This can only be reached from the backend.

You can go to the grid from anywhere in Deepser in the following way:

At the top right you can find the 3 dots: by clicking on them you will see the Task item and the Work Activity item.

By clicking WorkLog then we will access the grid that if not configured will show the following fields:

FIELDNOTES
ActionThrough a floating window, the entity in which the related work activity is contained is opened (for example, the ticket in which the activity is contained). Clicking inside the row instead opens in a floating window the work activity.
ModelA template that contains the activity of work (usually contained in operations, i.e., tickets)
Model IdThe id of the template in which the activity is contained. If the work activity is in a ticket, the Id of that ticket will be shown.
Visible to FrontendVisibility of activity in the front-end. By default, work tasks are never shown in the user portal.
Started AtThe date and time that indicates the start of the activity.
Ended AtThe date and time that indicates the end of the task.
DurationDuration of the activity.
Created ByThe user who created the task.
Created AtThe date and time that indicates the creation of the work task.
Updated AtThe date and time that indicates the last change in the work task.

Worklog Global Grid Configuration

EDIT GRID FIELDS

You can access the global grid configuration for work tasks through the edit button below.

Inside we could choose which fields to display and which not:

  • the available columns column lists all fields that are not shown in the grid
  • In the Visible Columns column, all the fields that are currently shown in the grid will be listed and we could choose in what order they will be shown in the grid.

To insert or remove fields from the grid, you can simply use the arrows at the ends of the fields.

To change the order of the fields shown you can use the Drag & Drop, then simply drag the fields.

By then clicking on one of the displayed fields, it is possible to define whether it is possible to make the field sortable, filterable and / or multifilterable in the case of a select field through the relative checkboxes.

 

COLLECTION OF ACTIVITIES DISPLAYED IN GRIDS

Within the grid in which we are located it is possible to define the collection of work activities that must be retrieved and shown in the grid through the appropriate Query Builder.

For example, you can view only the activities that have been placed within the tickets by setting the following control in the Query Builder: Model equal DeepService – Operation.

 

MASS ACTION AND EXPORTS

Through the Massive Actions checkbox, you can activate the massive actions in the grid.

Massive actions allow you to modify one or more work activities through a grid selection. The massive action that is currently implemented by default is that of elimination.

NB: Elimination through massive action will result in a physical deletion to databases. Deleted work tasks can no longer be recovered.

Through the Enable Export checkbox, on the other hand, it is possible to enable the export of the data displayed in the grid in XLSX or CSV format.

Once the export is enabled, a field will be shown in the grid that allows you to choose the format in which you want to extract the work activities and a button to export them.

Through the export will be extracted in the desired format the data of the work activities that are shown in the grid.

At the click of the sexport, you will be shown a popup that will ask if you want to export the only work activities visible at the time of export or if you want to export all the work activities.

Activity Global Grid Advanced Configuration

VIEW THE TITLE OF THE ENTITY TO WHICH THE WORK TASK IS ASSOCIATED

Some fields already present in the Work Activities may contain useful and convenient information to be displayed in the grid, in which, however, a brief configuration is required to make them actually usable.

In fact, we can see that if we want to view the contract or the contract line to which a work activity has been associated and we make the fields already available visible in the grid, some numbers will be displayed which will represent the ID of the relative entities.

To be able, for example, to view the name of the contract associated with a work activity, it is necessary first to go to the modification of the grid and make the Contract column visible.

It will then be necessary to click on the field just made visible and make a change on the type by setting it from Text to Options.

By pressing the </> key you can define custom PHP code for each column and change the printed value (Renderer) or change the options of a Field of type Options (Options).

In the Options field you will then need to enter the following custom code:

				
					// retreive of the Contract collection
$contractCollection = Deep::getResourceModel('deep_contract/contract_collection');
// convert the collection into an associative array
// the key is the Contract Id and the value the Contract Name
$optionsArray = $contractCollection->toOptionHash();
return $optionsArray;
				
			

Similarly, to view the name of the contract line associated with a work activity it is necessary to make the Contract Line field visible, change its type in Options and within the Options field to define custom code insert the following code.

				
					// retreive of the Contract Line collection
$lineCollection = Deep::getResourceModel('deep_contract/line_collection');
// convert the collection into an associative array
// the key is the Contract Line Id and the value the Contract Line Name
$optionsArray = $lineCollection->toOptionHash();
return $optionsArray;
				
			

At this point we may display the names of Contracts and Lines of Contracts that have been associated with the related work activities. We can also make these fields multifilterable and sortable.

MASS ACTION CONFIGURATION

It can often be helpful to set the same value to multiple tasks. In these cases, the use of mass actions is effective.

At the moment, the only massive action already prepared by the system in the grid of work activities is that for the (physical) elimination of one or more activities.

You can still configure a custom massive action by accessing the grid change. Below the Mass Action checkbox is the </> button that allows the opening of the custom PHP script area.

The following example shows the custom code that implements a massive custom action to enable or disable the visibility in the portal of one or more work activities.

The code must be inserted directly into the custom PHP script area.

				
					// create the array for the option visibility
$visibilityArray = [0 => 'No', 1 => 'Yes'];
 
// initialize html component
$this->addMassActionItem('visibility', [
    'label' => 'Visible to Frontend',
    'additional' => array(
        'visibility' => array(
            'name'   => 'visibility',
            'type'   => 'select',
            'class'  => 'required-entry',
            'label'  => 'Visible to Frontend',
            'disable_js_select' => true,
            'values' => $visibilityArray,
        )
    ),
    //callback is the method that contains the logic of the action
    'callback' => function() {
        /** @var Deep_Grid_Model_Grid_Massaction_Callback $this */
        /** @var Mage_Core_Model_Resource_Db_Collection_Abstract $collection */
        $collection = $this->getGrid()->getModelInstance()->getCollection();
         
        //$this->getIds() returns the id of the selected activities
        $collection->addFieldToFilter('entity_id', ['in' => $this->getIds()]);
         
        // $collection contains the instances of the selected activities and we iterate on them
        foreach($collection as $activity){
            //$this->getValue() contains the id of the new option visibility, the selected one
            //set the new activity visibility
            $activity->setPortalVisibility($this->getValue());
            //save the activity
            $activity->save();
        }
    }
]);
				
			

By inserting this script, it will then be possible to select one or more work activities and decide whether or not to make them visible in the end user portal.

Board

In Deepser there is a “Board” module.

The Board module allows you to create custom Boards in Kanban Format.

Kanban is a framework for Agile development that allows you to visualize your workflow, focus on progress, and optimize efficiency.

Deepser Boards can be of 2 types: FreeForm or Live.

In this course we will analyze everything related to Deepser boards.

Enable groups to create boards

To enable the groups to see the boards it will be necessary to go to the menu: System -> Configuration

At this point you need to go to the Tab Board -> Configuration

From the “policy” tab it will be possible to configure which groups will have the possibility to create boards  and board  freeform.

Creating a FreeForm Board

In Deepser to create a new board of type FreeForm You will need to go to the menu: Board -> List.

To create a new board once you go to the Board -> List menu you will have to click on the “+” button at the top left corner:

On the page that opens set the type to “FreeForm”.

At this point you can configure the name field with the desired name and the Description field with the description that will be displayed in the new board.

At this point you can check that the status of the board is set to “Enabled”  and click on the “Save” button to create the board.

At this point the new board will have been created.

Access a Board

To access a board you will need to go to the menu: Board -> List

At this point locate the board you want to view and click on the “View” button

Customize a board

To customize a board you will need to go to the menu: Board ->List, go to the three dots.

At this point it will be possible to add an icon by clicking the choose file button (3) or select a background for the board through the “background” or “background” selector (4), then click the “save” button (5).

For the logo it will now be present in the custom board.

To view the background you will need to go inside the board that you are customizing.

Share a Board

Deepser allows you to share a board in reading or reading and editing or reading, editing and interaction to allow you to make boards a very effective and immediate collaborative tool, suitable for the management of complex processes.

To share a board you will have to go to the menu: Board -> List.

From here you will need to click on the three dots placed on the board you want to share:

At this point the following screen will open:

The sharing fields are expressed in the following table.

FieldDescription
View UsersUsers who can view the board read-only
View GroupsGroups that can view the board as read-only
View and Interact UsersUsers who can view and move board items, but not edit or delete them
View and Interact GroupsGroups that can view and move board items, but not edit or delete them
View, Interact and Edit UsersUsers who can edit the board, move the Entries and delete them
View, Interact and Edit GroupsGroups that can edit the board, move the Entries and delete them

Note: In order to share a board it will be necessary that the user is registered with the system. In addition, in order for the user to view and interact with the board it will be necessary that he is a backend-enabled user and that he has a role where it is allowed to view the boards among the options in the side menu of Deepser.

Creating and customizing a Lane

A lane in Deepser is the entity within the boards that serves to contain and organize tasks in a logical way.

To create a Lane in Deepser you will need to go to the board where you want to add the wool, here you will have to click on the “+” button at the top right corner.

In the screen that opens you can set the name, filling in the “Label” field (2) and then click on the “Save” button (3).

Now the system will create the new Lane with the specified name.

Customizing a Lane

 To customize a Lane you will need to go to the Lane to customize and click the 3 points .

Here you can change the name or color of the Lane.

To change the name, simply edit the contents of the label field.

To change the color you will have to click on the color picker (2)

choose the desired color and click “save ” (3) and then the “Apply” button(4).

Finally, the Lane will be colored in the desired color.

 

Entry Creation

To create a new entry in the boards you will need to go to the section: Board -> List:

Then you will have to go to the board where you want to insert the Entry, in our example “Board Name”

Here, click on the “View” button

Once you enter the board you will need to identify the lane where you want to add the Entry

After that it will be necessary to click the “+” button in corrispondence of the Lane in which you want to add the Entry

At this point you will have to give a title tothe new  Entry and then click the tick button  

At this point it will be possible to see the new entry in the lane.

Move an entry between different lanes

To move an Entry to another Lane simply click on it and drag it to the new lane.

Once the Entry is released, the result will be as follows:

Board Live

The Live boards in deepser are a particular type of board, that instead of the entries allows to organize at logical level the entities inside Deepser.
In this lesson we will analyze how to create, customize and manage Deepser’s Live boards.

Live Board Creation

In Deepser it is possible to create in addition to freeform boards also live boards.

Live boards allow you to manage Deepser entities in graphical mode by representing the individual entity as an Entity of a board.

To create a live board you will need to go to the menu: Board -> List

Here you will need to click on the “+” button:

At this point the board creation screen will appear.

Here we are going to select as board type “Live” and as Model Alias “Deep service Operation”.

Similarly to the freeform boards also in the live board will be possible to insert an icon, to do so it will be sufficient to click on the button

Next we click the apply button to save the changes

At this point the live board will be created by Deepser.

The end result is as follows:

Now the board is configured for basic usage.

By default is configured to retrieve a collection of all Service  Operations. We will see in the next topic how to limit the number of  Operations or in  general entities of Deepser that can be recovered by applying filters to the collections of datas.

Collection Board Live Configuration

To configure the collection of a live board you will have to go to Board -> List

At this point you will have to go to the live board you want to edit and click on the three dots to access the configuration screen.

At this point you will have to go to the “Prepared Collection” section

Here it will be possible to configure which tickets will be viewable within the board.

For example, suppose you want to display only tickets in a new state or work in progress.

To do this, simply configure the query builder like this:

To finalize the changes you will need to click on the Apply button

Advanced Live Board Configuration

In this article we are going to deal with two examples of configuration of advanced live boards.

EXAMPLE 1

In this example we are going to replicate the configuration of the data collection of the previous board but using the scripting area present in the board.

To create a live board you will need to go to the menu: Board -> List

Here you will need to click on the “+” button:

At this point, the board creation screen will appear.

Here we are going to select as board type “Live” and as Model Alias “Deep service Operation”.

Similarly to the freeform boards also in live Boards it will be possible to insert an icon, to do so it will be sufficient to click on the button

Next we click the apply button to save the changes

Now we have to go to the scripting area, like the one shown in the figure:

In the scripting area that will open we are going to insert the following code:

				
					/* Only select tickets in New and Work in progress statuses**/
$this->getModelCollection() ->addFieldToFilters('status',["in"=>[1,2]]);
				
			

At this point we must go to click the save button to confirm the configuration.

EXAMPLE 2

In this example We are going to configure a live board that will load all the tickets for which the company of the requesting user has a flag set for priority assistance.

For this example we will assume that there is a “cust_prioritary_assistance” field in the company, of the checkbox type.

When the checkbox is flexed we will consider the company as a company with priority assistance.

To create a live board you will need to go to the menu: Board -> List

Here you will need to click on the “+” button:

At this point, the board creation screen will appear.

Here we are going to select as board type “Live” and as Model Alias “Deep service Operation”.

Similarly to the freeform boards also in live boards it will be possible to insert an icon, to do so it will be sufficient to click on the button

 At this point we can go to add in the scripting section of the board the following code:

				
					$this->getModelCollection()->getSelect()->joinLeft('deep_company_company','main_table.requester_company_id = deep_company_company.entity_id',[]);
$this->getModelCollection()->addFieldToFilter('deep_company_company.cust_prioritary_assistance', 1);
				
			

Now we must click on the Save button to save the board.

Creating and customizing a Lane

A Lane in Deepser is the entity within the boards that serves to contain and organize in a logical way the entities loaded by the board.

To create a Lane in Deepser you will need to go to the board where you want to add the wool, here you will have to click on the “+” button at the top right corner.

In the screen that will open you can set the name, filling in the “Label” field.

At this point you can enter a new field in the Field field to display. In this case we enter the field “entity_id”of the ticket. By clicking on the button

At this point we select in the Field field the value “entity_id” and in the label field “Yes”.

At this point you will need to click on the apply button.

Now the system will create the new Lane with the specified name.

CUSTOMIZING A LANE

The following properties of a lane can be customized: the name,  the color of the Lane, the data collection, the Drop Code or the fields to be displayed for each ticket in that Lane.

CHANGE THE NAME OF THE LANE

To change the name, simply edit the contents of the label field.

Next you will need to click on Apply:

CHANGING THE COLOR OF A LANE

To change the color of the Lane you will need to go to the Lane to customize and click the 3 points.

Here you can select the color to assign to the Lane using the color picker:

choose the desired color and click “Save”:

and then the “Apply” button:

Finally, the Lane will be colored in the desired color.

PREPARED COLLECTION CUSTOMIZATION

In Deepser’s live boards Lanes  the prepared collection section is used to define which tickets will be displayed in the Lane.

To customize the prepared collection of a Lane in a live board you will need to go to the Lane to customize and click the 3 points.

Now it will be possible to set the data collection to be displayed in that lane through the “Prepared Collection” section

Let’s say you want to display in this Lane only the entities in a state new, you can do it through the query builder:

At this point click on the “Apply” button:

Now the lane will be updated automatically by the system loading only the tickets that correspond to the filters set

CUSTOMIZE THE DROP CODE

The drop code in Live boards is the code that is executed when a ticket is dragged onto the board.

To customize the drop code of a Lane in a live board you will need to go to the Lane to customize and click the 3 points.

Here you will be able to set the code to run in the “Drop Code” section via the query builder.

In the current example, let’s say we want to set that when a ticket is dragged into this section it takes on a new state:

At this point when a ticket is dragged on this board, its status will change to new.

Creation and Advanced Configuration of a Lane and Drop Code

A Lane in Deepser is the entity within the boards that serves to contain and organize in a logical way the entities loaded by the board.

In this article we will see an example of advanced lane configuration using the scripting area on the lane and an advanced example of changing the Drop Code of a lane.

EXAMPLE 1

In this example we are going to show in the lane only the tickets in The New state, by default id 1.

To Edit a live lane you will need to go to the board where you want to change the wool, here you will have to click on the three dots:

At this point we will have to go to the scripting area “Data Collection (Script)” as in the figure shown here:

Here we are going to enter the following code:

				
					/**Visualizing only the ticket in with state "NEW"**/
$this->getModelCollection()->addFieldToFilter('status',["eq"=>1]);
				
			

At this point click on the “Apply” button:

Now the lane will be updated automatically by the system loading only the tickets that correspond to the filters set

Customize the Drop Code

The drop code in Live boards is the code that is executed when a ticket is dragged onto the board.

To customize the drop code of a Lane in a live board you will need to go to the Lane to customize and click the 3 points.

In the current example, let’s say we want to set the company as a company with priority assistance when a ticket is dragged into this Lane.

To do this we insert in the scripting area “Drop Code (Script)”:

the following code:

				
					/**Setting prioritary assistance for the company of the dropped ticket **/
$company = $this->getDroppedModel()->getRequesterCompany();
$company->setData('cust_prioritary_assistance',1)->save();
				
			

At this point click on the “Apply” button:

At this point when a ticket is dragged on this board its status will change again.

Categories

Categories in Deepser are an important tool for the management of Tickets, CIs, or the Deepser entities in general  by backend side operators.

The Categories allow you to describe quickly and concisely the scope of that specification required, for greater flexibility Deepser allows you to organize the categories on a hierarchical scale of up to three levels which translates into being able to have a first level category with N categories of second level and each of them with N categories of third level.

Category Overview

Categories in Deepser are an important tool for the management of Tickets, CIs, or the Deepser entities in general  by backend side operators.

The Categories allow you to describe quickly and concisely the scope of that specification required, for greater flexibility Deepser allows you to organize the categories on a hierarchical scale of up to three levels which translates into being able to have a first level category with N categories of second level and each of them with N categories of third level.

The categories in addition can be visible on one or more types of service or some categories can be visible only by some groups of users, this allows you to manage in a granular way the categorization of tickets, in addition they can be enabled and therefore visible or be disabled and therefore not displayed within the appropriate field.

In addition, they can be used as parameters in routing rules (Automatic assignment of tickets, these will be covered in a later lesson) to assign a ticket to a user or group based on the category.

Category Hierarchy

Categories in Deepser are organized in a hierarchical tree structure of up to 3 levels.

So each first level category corresponds to zero or more second-level categories, and for each 2-level category zero or more third-level categories correspond.

This structure is called hierarchical because if you apply visibility restrictions on a higher-level category, the lower-level categories will inherit those limitations.

Categories in addition can be made visible for all models, by default, or only for a specific model.

Category Configuration

Creating New Category In Deepser

To create a new category in Deepser you will need to go to the menu: System -> Categories

At this point, you will need to click on the “Add Root Category” button

At this point, the following screen will open:

Below are the fields with their meanings:

FieldDescription
NameThis field is the name that the new category will have.
DescriptionThis field is the description that will be associated with the new category
ImageThis is the icon that will be displayed side by side next to the category name (only if this field is filled in)
StatusThis field is the status that will have the new category: if the status will be enabled then the category will be displayed among the usable and selectable categories, otherwise it will not be displayed among the categories.
Frontend VisibilityThis field indicates whether this category will be viewable among the categories in the guest portal (only if the guest portal is enabled)

Once you have filled in the fields, you can click on the “Save Category” button

Creating New Sub-Category in Deepser

To create a new subcategory in Deepser you will need to go to the menu: System -> Categories

At this point, you will need to select the category that will become the parent of the new subcategory and click on the “Add child Category” button

Now the following screen will open:

Below are the fields with their meanings:

FieldDescription
NameThis field is the name that the new subcategory will have.
DescriptionThis field is the description that will be associated with the new subcategory
ImageThis is the icon that will be displayed side by side next to the subcategory name (only if this field is filled in)
StatusThis field is the status that the new subcategory will have: if the status will be enabled then the category will be displayed among the usable and selectable subcategories, otherwise it will not be displayed among the subcategories.
Frontend VisibilityThis field indicates whether this category will be viewable among the subcategories in the guest portal (only if the guest portal is enabled)

Once the fields have been filled in, it will be possible to click on the “Save Category” button.

Category Visibility Management

Model Visibility

On model visibility tab you can limit the usage and access of a category on a model. For example, you can set a category to be visible only on operation model.

To configure a new model visibility, just click on the ‘+’ button inside model visibility tab.

Model Visibility – Example

Below there is an example of a model visibility, that limits the ‘User Equipment’ category to only operations of type ‘Request’ and ‘Incident’. When users open a ticket of type ‘request’ or ‘incident’, they will be able to view and use the ‘User Equipment’ category.

Field

Description

Model

Select field where you can choose the model which will have visibility to this category.

Portal Visibility

With this field you can make the category visible or not on End Users portal.

Frontend Visibility

Select field with Yes/No values , that can set the category visible on frontend portal.

Expression

Query Builder field that adds another layer of visibility on the category. With this field you could limit the visibility of a category if certain conditions based on model’s fields, are met.

Expression (Script)

Scripting field that has the same functionality as the query builder, but here you can write the conditions directly by code.

Group visibility

By configuring group visibility you can limit, users access to a category based on the group that they participate.

To set group visibility, just go under group visibility tab and select the groups of visibility on the ‘Enabled Groups’ field. In the example below, the “User Equipment” category is visible only for users that are part of “IT- First Level” or “IT Customers” groups.

Guest Portal Visibility

To make a category visible in the guest portal, you need to go to the menu: System  -> Categories.

Here, you will need to click on the category we want to change.

At this point, we must change the field “Portal Visibility” to “Yes”

Finally, we must click on the “Save Category” button.

Category Usage

Categories in Modules

The usage of categories is available by default in Operation or CMDB models, through a custom field with element type ‘category’.

  • Category field configuration

This is how to category field shows on the formtemplate after configured.

On the first select field there are shown all the Categories of level 1. After a first category is chosen the select of second categories is shown and so on.

Categories in Grids

Categories of different levels can be used on grids of the models that have the category field configured. To be able to display the categories fields in grids, fields should be dropped on the visible columns of grid. The column type should be ‘options’ , so that the category name is displayed and not its entity id.

After adding the categories this is how they will appear on the grid.

Chat

Do you need more informations about of Deepser’s integrated Chat Advanced Configuration? We will explain everything about Public Channel, Chat Widget Integration, etc..

Using the Chat

Deepser offers an integrated chat, that allows you to collaborate internally with registered users, or receive requests from external users.

If properly configured, the chat module is accessible in two different ways:

1 – Using widgets, generally at the bottom right.

1b – The chat widget looks like this:

2 – By clicking on the Chat entry in the Deepser backend menu.

2b – This is how the backend chat module shows up:

NameDescription
ChannelsChannels where a certain number of users can communicate, possibly organized by topic.
DirectDirect communication between two users.

3 – To start communicating with a single user, press on the users icon.

4 – Select the user to start the chat with, then press Create Direct Chat.

5 – This is the direct chat section.

The meaning of the elements is the following:

ElementMeaning
Reply ButtonIt allows users to send normal messages in the chat, which can be viewed by the other participants of the group or by the recipient user.
Private Note ButtonIt allows the creation of a private note within the chat, not visible to other users.
Staple iconIt allows sending files as attachments in chat.
Emoji IconIt allows the insertion of an emoji in chat.
Send ButtonAllows you to send the message.

Enabling the Chat on Portals

1 – Access the system chat configuration, via System->Chat->Configuration

2 – To view the chat widget in the user portal, set “Enabled in Portal” as Yes,to make it available instead in the Guest portal, set Enabled in Frontend as Yes, finally press Save Config

Note: Public Chat Enabled Groups indicates the groups that will be enabled to manage public chat messages.

Max Attachment Size indicates the maximum size of attachments.

3 – To apply the configuration, reboot the Chat Websocket Server.

4 – Once the steps are completed, the chat widget will appear in the portals where it has been enabled.

Chat Rooms and Moderators

Deepser chat allows Key User, Agent and Admin to create Rooms .

Channels are spaces where multiple users can communicate, usually about a particular topic.

Let’s proceed with the creation of a channel.

1 – Press the Room creation button

2 – Enter a Name for the Room , and the list of participating users, then press Add room .

3 – Press on the three dots at the top left, then Edit Room.

 

4 – The channel editing menu will be displayed, with the possibility to add Moderator users.

This table describes the permissions of the room creator, moderators and end users.

 End UserModeratorsCreator
Edit/Delete RoomThey cannot create rooms or become moderators, but they can be added to a room .BothBoth
Edit/Delete MessagesThose of which it is senderAny messageAny message  
Add/Edit ModeratorsNoNoBoth
Remove the Creator from the ChannelNoNoNo

Note: As can be seen from the table, no one, not even the creator himself, can remove himself from one of his channels.

Public Chat

Deepser’s public chat, is a front-end chat available as a widget in any website or web service, through a script.

This type of communication, allows any unregistered user to send a message, which will then be managed in the Key User, Agent and Admin, if enabled.

Any communication made through the public widget, or in the guest portal, will appear in the Deepser backend, and will be identified by a unique code, representing the cookie released in the machine of the user who sent the message.

On the other left you can see the three statuses of a Public chat:

  • Not Assigned: The chat has yet to be assigned to a Key User, Agent or Admin, so any user correctly configured with one of these roles can see the message, but not respond until it is assigned.
  • Assigned: The chat is visible only to the assignee user, who can respond.
  • Resolved: The conversation has come to a conclusion.

To assign a chat, click on the icon at the top right, else to just choose to manage the request personally, click below the message.

To mark a conversation as resolved, press the tick button instead.

The user will then see the answer

Deepser’s public chat, is a front-end chat available as a widget in any website or web service, through a script.

This type of communication, allows any unregistered user to send a message, which will then be managed in the Key User, Agent and Admin, if enabled.

Any communication made through the public widget, or in the guest portal, will appear in the Deepser backend, and will be identified by a unique code, representing the cookie released in the machine of the user who sent the message.

Configure a Public Chat Widget

Deepser allows a website integration with the frontend chat, thanks to a dynamically generated script based on the parameters entered.

1 – Go to System->Chat ->Widget Configuration, then press ‘Add Widget configuration’.

2 – The widget configuration form will open, fill in the fields with the requested values, then Save.

This is the meaning of the fields:

FieldDescription
NameSets the name of the widget
DomainsSets the list of domains, from which it is allowed to call the widget, through the script
PositionSets the position where the widget will appear (bottom right/bottom left).
ColorSets the color of the widget.
TextSets the text that will appear in the bubble icon to open the widget.
Website NameSets the name of the website that will appear in the widget
Welcome TitleSets the welcome title that will appear once a user opens the widget for the first time.
Welcome TaglineSets the welcome subtitle that will appear once a user opens the widget for the first time.  
Can Send AttachmentsAllows the user to send files in the chat.
StatusThe status(Enabled/Disabled)
TokenIt’s the string that identifies the external implementation of the chat widget, it is automatically set when saved.
Widget ScriptField generated dynamically when saving, containing the scripting code, to be inserted to integrate the chat externally.

3 – Once saved, the token and the Widget Script will appear. This is the script to insert on the site to integrate the chat; copy the code by clicking on the scripting area.

3a– Enable Backend and Frontend to run in frame, in System->Configuration->Admin->Allow Backend to run in frame and Allow Frontend to run in frame

4 – insert the code on the page where you want the support widget to appear.

5 – If the integration was successful, the configured widget will appear at browser cache refresh.

6 – To enable groups to mange public chat messages, go to System->Configuration->Chat->Configurations, then set some groups in Public Chat Enabled Groups.

Chatbot

Chatbot – Flow

First of all, to trigger the flow the frontend must be enabled.

You can enable frontend on System -> Configuration.

After it, you must enable the chat on the frontend.
You can enable frontend on System -> Configuration -> Chat -> Configurations

Here, on Configurations -> Enabling, you will have to enable the “Enabled in Frontend” field.

The functionality behind the Bot in Deepser lies behind a flow with a trigger of type chatbot. The Chatbot flow trigger type is executed every time a new chat is created in the frontend area.

Create a Bot

  1. To create a bot, open System > Chat > Bot and click the button “Add Bot”.

2. Configure your bot

Field

Description

Name

The name of the Bot.

Flow Heather

The flow to which the Bot is connected.

Status

Status of Bot. It can be enabled or disabled.

Avatar

The image of Bot.

After it, we have to open the template of the chat. We must add to the form the field “Bot”.

Chat Bot Actions

Send Message

This action type is used to directly send a text message on the created chat.

To configure this, you need to open the “Send Message” script. For do this, click “”.

  1. Open: Action > Chat Bot > Send Message.

2. Write your message in the field called “Message” and, after it, click “Save”.

Ask For Details

This action is used to send a message in the form of a question that waits for a response.

The response can be of type String or Attachment. This response can be used as a variable later on the flow.

To configure this, you need to open the “Ask For Details” script. To do this, click “+”.

  1. Open: Action > Chat Bot > Ask For Details.

2. Write your message in the field called “Message” and after click “Save”.

Present Options

By using this action, on the chatbot will appear a message in the form of a select field from which the user can select only one answer and cannot type a custom message or add an attachment. The options are mapped through the “value” field which has the role of a key and the “label” field which is the visible option to the user.

To configure this, you need to open the “Ask For Details” script. To do this, click “+”.

  1. Open this: Action > Chat Bot > Present Options.

2. Write your message in the field called “Message”, insert your options on field “Options” and save clicking the button “Save”.

If you set the field “Add Variable Options” to “ON” you have the opportunity to add an array of options that are retrieved from upper steps of the flow and set to an output variable.

Chat With Operator

By using this action, the chat is assigned to a specific user present in Deepser who can be an administrator, agent, key user.

Frontend User
Backend User

With this action, the assigned user can then chat directly with the frontend user.

To configure this, you need to open the “Chat With Operator” script. To do this, click “+”.

  1. Open: Action > Chat Bot > Chat With Operator.
  1. Message

On this field is written the text that will be displayed on the chat, informing the frontend user that from now on their request will be assigned to an agent.

  1. Notification Message

This field contains the text message that will be sent to the assigned user.

  1. Operator

This field holds a variable of type DeepAdmin- User Model and here is where we assign the user variable retrieved from upper stages of the flow.

Chatbot Flow - Example

Introducion

On this page we will explain how to set up an example chatbot.

In this example, when a frontend user needs to have some information, the chatbot will assign the chat to the correct backend operator.

For this we will use three different users:

Trigger

First we will insert the type of trigger as Chatbot

From this block we will get the following variables:

Variable

Description

Bot

The model of the bot and contains all formtemplate fields.

Room

This variable represents the chat room.

All Room Form Fields

This variable contains all formtemplate fields of room model as an array

Block 1

In this block we will insert a welcome message into our frontend chat:

When the frontend user starts the chat, the message written in the “Message” field (image above) will be automatically sent to him.

From this block we will not get variables to use later if necessary.

Block 2

Here, let’s see how to ask the frontend user to enter their first and last name. This information will then be used to rename the room.

The message written in the field will be sent immediately after the welcoming one.

The user will reply to the message from the chat by entering the requested information.This information will be saved in the “Respond” variable.

With this block we will get the following variables:

Variable

Description

Response

The response entered by the frontend user

Attachments

The possible attachments inserted

Attachments Count

Sum of attachments

Block 3

With this block we are going to rename the chat room name on the backend side.

N°

Description

Note

1

Let’s choose the “Update Record” block.

This way we can change the name of the room

2

Let’s choose the chat room as our model.

The response is one of the variables obtained in the trigger (block 1)

3

Let’s enter the “Name” field in the query-builder, which will be valorized with the user’s response

The answer is one of the variables derived in block 3

Note: This configuration will work when the “Chat with Operator” block is added.

 

With this block we will get the following variable:

Variable

Description

(Model) DeepChat – Room

Room template with updated name

Block 4

In this block we will see how to insert three options of your choice.

N°

Description

Note

1

Let’s choose the “Present Options” block.

In this way we can create the options that will later be shown to the frontend user

2

Variables addition

Optional, in this example we take as input the name provided to the user.

3

Let’s enter the message that will appear as a header to the options

Here, the text {{var name}} is used to enter the user’s name, entered as input

4

Added options that the user will have available to them

 

The following message will be sent to the user:

Clicking the square of the chosen answer will automatically send the choice as if it had been written by the user

With this block we will get the following variables:

Variable

Description

Response

The response entered by the frontend user (string)

Value

Response value

Block 5

In this block, we will enter the condition “if option 1 was chosen.”

N°

Description

Note

1

Let’s choose the “If” block.

 

2

Let’s set the desired condition

In this case we set user-chosen value is “support incident/request”

Block 6

Entry into this block will only occur if the frontend user chooses “support incident/request”(1) as an option.

Here, we will retrieve the “Support” user, who will be the operator to whom the chat will be sent.

N°

Description

Note

1

Let’s choose the “Lookup Record” block.

This will allow us to retrieve the user “Support”

2

Let’s choose the model “DeepAdmin – User”

 

3

As a filter let’s enter the “user_id”

In this example, the user “Support” has id 53

With this block, we will get the following variables:

Variable

Description

(Model)DeepAdmin – User

Model with user data

Model Alias

For this model it will be “deep_admin/user”

Block 7

This block will handle the handover of the chat to the “Support” operator.

N°

Description

Note

1

Let’s choose the block “Chat with operator”

 

2

Field in which a message can be inserted for the frontend user

Optional

3

Field in which you can enter a message for the operator

Optional

4

The user retrieved in block 6 is inserted from the variables

Optional, if left blank it will be sent to all enabled users.

Block 8

In this block, we will insert the condition “if option 2 was chosen.”

N°

Description

Note

1

Let’s choose the “else If” block.

 

2

Let’s set the desired condition

In this case, the value chosen by the user is “sales problem/request”

Block 9

Entry into this block will occur only if the frontend user chooses “sales problem/request”(2) as an option. Here, we will retrieve the user “Sales,” which will be the operator to whom the chat will be sent.

N°

Description

Note

1

Let’s choose the “Lookup Record” block.

This will allow us to retrieve the user “Sales”

2

Let’s choose the model “DeepAdmin – User”

 

3

As a filter we enter the user_id

In this example, the user “Support” has id 54

With this block, we will get the following variables:

Variable

Description

(Model)DeepAdmin – User

Model with user data

Model Alias

For this model it will be “deep_admin/user”

Block 10

This block will handle the handover of the chat to the “Sales” operator.

N°

Description

Note

1

Let’s choose the block “Chat with operator”

 

2

Field in which a message can be entered for the frontend user

Optional

3

Field in which you can enter a message addressed to the operator

Optional

4

The user retrieved in block 9 is inserted from the variables

Optional, if left blank it will be sent to all enabled users.

Block 11

In this block, we will insert the condition “if option 3 was chosen.”

N°

Description

Note

1

Let’s choose the “else If” block.

 

2

Let’s set the desired condition

In this case, the value chosen by the user is “administration incident/request”

Block 12

Entry into this block will occur only if the frontend user chooses “administration incident/request”(3) as an option.

Here, we will retrieve the “Administration” user, which will be the operator to whom the chat will be sent.

N°

Description

Note

1

Let’s choose the “Lookup Record” block.

This will allow us to retrieve the user “Administration”

2

Let’s choose the template “DeepAdmin – User”

 

3

As a filter we insert the user_id

In this example, the user “Support” has id 55

With this block, we will get the following variables:

Variable

Description

(Model)DeepAdmin – User

Model with user data

Model Alias

For this model it will be “deep_admin/user”

Block 13

This block will handle the handover of the chat to the operator.

N°

Description

Note

1

Let’s choose the block “Chat with operator”

 

2

Field in which a message can be entered for the frontend user

Optional

3

Field in which you can enter a message for the operator

Optional

4

The user retrieved in block 12 is inserted from the variables

Optional, if left blank it will be sent to all enabled users.

CMDB

The cmdb in Deepser is a database made available to the user.

It is the tool used to create records (Custom item or CI) and store the information, organised by a Type, a Subtype and a Class.

In this course we will deal with the CMDB in all its parts.

Deepser CMDB

The CMDB in Deepser is a database made available to the user.

It allows you to create records (Configuration item or CI), each of them characterized by a Type, a Sub Type and a Class.

Classes

Classes make it possible to distinguish ci into macro categories.

The defined macro categories will be displayed on the backend side inside the CMDB menu as shown in the figure below.

Types

Types allow you to add a type layer to the elements defined in the classes.

On one hand, it allows you a more granular management of visibility permissions.

On the other hand, it allows us to make it more immediate to understand what that particular refers to.

Subtypes

Subtypes allow you to add a type layer to the elements defined in the Types.

This allows on the one hand a more granular management of visibility permissions; on the other hand, it allows us to make it more immediate to understand what that particular refers to.

THE CI

As mentioned above, there are similar to records in a database that allow you to create custom entities within Deepser.

These entities can be assigned to users who will be able to view and edit these entities.

An example of use is for example the management of the devices assigned to the users, in this case once assigned the ci to the user, it will be able to display any information concerning the device itself for example serial number, any pins or associated codes or any other kind of information that may be useful to manage for the assignee user.

Types allow you to add a type layer to the elements defined in the classes.

This allows on the one hand a more granular management of visibility permissions; on the other hand, it allows us to make it more immediate to understand what that particular refers to.

Enable CMDB in the User Portal

To enable the cmdb in the user portal you will need to go to the menu: System->Configuration.

Here it will be a must to go to the “Portal” item.

At this point, the following screen will open:

You will need to set the “Enable” field to “Yes”, this will enable the CMDB for the user portal.

The default “Enabled Priority” field on “Global” allows you to specify whether the CMDB will be enabled for all users (default) or if set to “User” it will be enabled only for users for whom the Portal CMDB Visibility field has been set to “Yes”.

User Portal CMDB Grid Configuration

To configure the CMDB grid in the user portal, you will need to go to the menu: System->Portal->Ci.

Here you can configure the grid using the pencil button at the top left.

Once you click the pencil button, both will open the following screen:

Here, you can insert new fields in the grid by dragging them from the “Available Columns” column to the “Visible Columns” column.

As per the image below.

In addition, from here it will be possible to modify what will be visible through the configuration of the query builder, in the example below we want to make visible only those that belong to the “Locations” class.

Note that these configurations will apply to all end users, to make a more granular configuration it will be possible to implement a custom script, as we will see in the next lessons.

Advanced Configuration of CMDB Grids

In Deepser you can define a custom script that allows you to specify advanced conditions for the collection of us to be displayed.

Example 1

In this case we suppose we want to make visible only to some End-users all the categories of the  CMDB, all the others we want to display only on the CI of class 1 (Location).

To do this, we must go to the menu: System -> Portal -> CI.

Here, we will have to click on the pencil-shaped button.

Now the following screen will open:

In the “Prepared Collection Script” section, we are going to insert the following code:

				
					//Array of technicians, who can see all the cis
$technicians = ['deepser_tec','mario.rossi'];
 
//if the current user is not in the technicians array he or she colud only see cis with class_id 1
if((!is_null($technicians) && is_array($technicians)) && (!(in_array(Deep::helper('deep_admin')->getCurrentUser()->getUsername(),$technicians)))){
     $this->getCollection()->addFieldToFilter('class_id', [ "eq" => 1 ]);
}
				
			

Note: that the array technicians contain the usernames of the users and not the Display usernames.

Once this is done, you will need to click on the “Save” button to save the changes.

Example 2

In this case we suppose we want to make visible only to some End-users all the categories of the CMDB, all the others we want to have visibility only on the class 1 CI (Location), compared to the previous case in this case we are going to define a custom field of checkbox type that will allow you to define in a simpler way    which users will be able to view all the ci.

To create the custom field, we must go to the menu: System -> Custom Fields

Here we will have to go in user model.

At this point in the “Fields” section, we are going to click on the “Add Field” button.

Now the following screen will open:

Here we are going to define the “Code” field as “is_cmdb_technician”.

The “Label” field will instead be “Is Technicians”.

Now, we configure “Column type” as “Integer”.

At this point, we define the “Element Type” field as “Checkbox”.

As a last step, going to the “extra” tab we set the flag: “Render as Toggle” to “Yes”.

At the end, click on the “Save” button to save the custom field.

At this point, it will be necessary to insert the newly created field in the users’ template form, and we will enhance it for those users who will have to see all the CI.

Now to implement the actual filter, we must go to the menu: System -> Portal -> CI.

Here, we will have to click on the pencil-shaped button.

Now the following screen will open:

In the “Prepared Collection Script” section, we are going to insert the following code:

				
					$userArray = Deep::getResourceModel('deep_admin/user_collection')->addFieldToFilter('cust_is_cmdb_technician',[ ["neq" => 1], ['null' => true]]);
 
$userlist = [];
foreach($userArray as $user){
  $userlist[$user->getUsername()] = $user->getDisplayUsername();
}
if(( !is_null($userlist) && is_array($userlist)) && (array_key_exists(Deep::helper('deep_admin')->getCurrentUser()->getUsername(),$userlist))){
     $this->getCollection()->addFieldToFilter('class_id',["eq" =>1]);
}
				
			

Once this is done, you will need to click on the “Save” button to save the changes.

Class, Type and Subtype

In Deepser Cis Class, Type and SubType are organized in hierarchical ways starting from the highest level of the hierarchy we have the classes; each class can then be associated with one or more Types and at the end of each Type will be associated one or more SubTypes.

In this guide we will see how to configure the hierarchy of classes, Type and SubType.

Class

To configure a new class, you will need to go to the System -> CMDB Configuration-> Class menu.

Here, you will need to click on the “Add Class” button.

At this point, the following screen will open:

Below is a table with the name of the fields and their meaning:

FieldDescription
NameThe name of the class.
StatusThe Status of the class, if “Enabled” the class will be displayed otherwise it will be  neither  viewable  nor  setable and with it will also be hidden the ci of that class.
Enabled GroupsGroups that can see that class and interact with the
IconClass icon, it is used to make it easier to recognize the class at first glance.
PositionPosition of the class, this field will allow you to define the order in which the classi will be displayed in the sidebar.

Once you have filled in the fields in the desired way, you can click on the “Save” or “Apply” button to save the class

Type

To configure a new Type, you will need to go to the System -> CMDB Configuration-> Type menu.

Here, you will need to click on the “Add Type” button.

At this point, the following screen will open:

Below is a table with the name of the fields and their meaning:

FieldDescription
ClassThe class to which the Type belongs.
NameThe Name of the Type.
StatusThe Status of the Type, if “Enabled” the Type will be displayed Otherwise essor will not be viewable or settable.
IconClass icon, it serves to make it easier to recognize the Type at first glance.
PositionLocation of the Type, this field will allow you to define the order in which the Types will be displayed.

Once you have filled in the fields in the desired way, you can click on the “Save” or “Apply” button to save the  type.

SubType

To configure a new Subtype, you will need to go to the System -> CMDB Configuration->SubType menu.

Here you will need to click on the “Add SubType” button.

At this point, the following screen will open:

Below is a table with the name of the fields and their meaning:

FieldDescription
TypeThe Type to which this Subtype will be associated.
NameThe Name of subtype.
StatusThe Status of the Subtype, if “Enabled” the Subtype will be displayed Otherwise essor will not be viewable or settable
IconSubtype icon, it is used to make it easier to recognize the Subtype at first glance.
PositionLocation of the Subtype, this field will allow you to define the order in which the Subtypes will be displayed in the sidebar.

Once you have filled in the fields in the desired way you can click on the “Save” or “Apply” button to save the Subtype.

Configuring a CI

To create a new CI in Deepser you will need to go to the menu: CMDB-> All.

Here you can click on the “Add Us” button.

Now in the window that will open you will need to choose the type of us to create and then click on the “New” button.

At this point, the following screen will open:

Below is the name of the fields and their meaning:

NameMeaning
NameName that will be associated with the new CI.
CategoryThe category associated with what you are creating. 
ClassThe class of CI.
TypeThe Type of the
SubtypeThe SubType of the CI.
DescriptionDescription Del CI.
Serial NumberSerial Number  of the CI.
Front ImageFront image of the CI.
Business ImpactImpact on the business of the CI in question. This field indicates how important this is to the company’s business.
PriorityPriority of the CI.
UrgencyUrgency of the CI.
NotesNotes Associated with this there.

In the “User Details” tab, there will be the following fields:

Below is the name of the fields and their meaning:

NameDescription
Owner CompanyCompany that owns the company
Owner GroupGroup owner of the CI
Owner UserUser owner of the CI.
Assigned CompanyCompany assigned to us
Assigned GroupAssignee group of the CI
Assigned UserUser assignee of the CI.
Updated ByThe last user who updated the CI, at the beginning will be the user who created the CI.

In the “Activity/Attachments” tab, there will be the following fields:

Below is the name of the fields and their meaning:

NameDescription
TaskTasks Associated with CI. Before we can enter tasks associated with this, we will need to save it at least once.
ActivitiesActivities associated with the CI, could be comments or worklogs associated for example with the maintenance of the CI.
AttachmentsAttachments of the CI, this field can be used to upload files that regarding a CI.

In the “Relations” tab there will be the following fields:

Below is the name of the fields and their meaning:

NameDescription
Relation to Other CIsThis field will show relationships with others there (when present)

In the “History” tab, there will be the following fields:

NameDescription
History ChangesThis field will contain the list of changes made to this field so that you know who made changes on it.

Once you have filled in the fields, you can click on the “Save” button to save the CI just valued.

CRM

 

Deepser’s CRM (Customer Relationship Management) module is used to manage, control and maintain a Customer, Contacts and Customer Base. It is also possible to Manage Sales Opportunities, tracking their possible profits, probabilities and related Tasks

Deep CRM

Deepser’s CRM (Customer Relationship Management) module is used to manage, control and maintain a Customer, Contacts and Companies Park. It is also possible to Manage Sales Opportunities, tracking their possible profits, probabilities and related Tasks.

The CRM consists of three categories:

  • Account: Allows to Maintain Data Relating to Customer Companies and Related Divisions

  • Contacts: Tracks Contacts and Leads

  • Opportunities: Organize business opportunities and describe the next steps to take

Creating an account in the CRM

The following guide addresses the issue of creating an Account in the CRM, explaining the meaning of the standard input form fields.

1 – Open CRM – Account, Via CRM -> Account

2 – The following fields will be displayed in the Insert Form:

The meaning of the fields is as follows:

CampDescription
NameThe Company Account Name
TypeIndicates the type of Account
Parent AccountAllows you to Establish a hierarchy between different accounts. He then manages Divisions and Corporate Headquarters. For example, an ACME Account may be parent of ACME Italy and ACME France.
StateEnable or Disable L Account
Linked CompanyField that maintains a reference to a Company present in Deepser Companies. (See the section Buttons)
Owner UserAllows you to specify the Account Administrator.
WebsiteMy Account website
PhoneYour Account Phone Number
FaxFax of Account
IndustryArea of Account Reference
EmployeesNumber of Employees
Satisfaction RatingCustomer Account Satisfaction Level
LogoAccount Logo Image
NotesAdditional Notes
TaskTask Related to Account

Creating a contact in the CRM

The following guide addresses the issue of creating a Contact in the CRM, explaining the meaning of the standard input form fields.

1 – Open the CRM and Select the type of contact concerned, via CRM -> Contacts

1a – The insertion form consists of two sections:

  • Contact: Contains contact details
  • Contacts: Contains contact details such as phone number, email, etc.

2 – The following fields will be displayed in the Contact Entry Form:

The meaning of the fields is as follows:

CampDescription
NameName of the Contact
SurnameSurname of the Contact
SalutationAllows you to Pin the greeting with which Refer to the contact (e.g. Lady or Miss)
StateEnable or Disable L Account
DepartmentThe Department to which the Contact belongs
QualificationThe status of the Contact
ManagerAllows Specifying a Contact Manager
SourceIndicates the source from which the Lead was generated
RatingCustomer Account Satisfaction Level
Associate userAllows Associating Contact to a System User on Deepser
TaskTask Related to Contact

The Contacts tab contains the followingfields:

The meaning of the fields is as follows:

CampDescription
EmailEmail of the Contact
TelephoneNumber of Fixed Telephony
Mobile phoneNumber of Mobile Telephony
FaxFax of the Contact
AddressAddress of the Contact
CityCity of Contact
ProvinceProvince of Contact
CAPCap of the Contact
StateState

Creating an opportunity in the CRM

The following guide addresses the issue of creating an Opportunity in the CRM, explaining the meaning of the standard input form fields.

1 – Open the CRM – Account, Via CRM -> Opportunity

2 – The following fields will be displayed in the Insert Form:

The meaning of the fields is as follows:

SectionFieldsDescription
Expediency                TitleThe Company Account Name
 State Indicates the type of Account
 Typology BusinessIndicates the type of Opportunity
 AccountIndicate the reference account
 ContactingIndicates the reference contact
 DescriptionAllows you to enter a description of the opportunity
 User OwnerAllows to indicate a user owner of the Opportunity
 SourceIndicates the source that generated the following opportunity
 Loss ReasonIndicates the reason that led to the loss/renunciation of opportunity
Amounts    AmountSpecify the sum of money that could generate the opportunity
 Budget Confirmed Indicates the confirmation status of the Sum
 ProbabilityIndicates the probability of obtaining this sum
Step  Next Step TitleIndicates the title of the next step needed to get the opportunity.
 Next Step DescriptionIndicates the description of the next step needed to get the opportunity.

Contact Types in CRM

The following guide deals with the creation of a customized Contact Type, in addition to those already present in the system, Contact and Lead.

1 – Open the system configuration for Contact Types, via System-> CRM Configuration -> Contact Types

2 – Click Add Type Contact

3 – Below is the standard Insert form

The meaning of the fields is as follows:

FieldDescription
NameThe name of the type of Contact
ClassIndicates the class of the Contact type
DescriptionIndicates the description of the type of Contact
IconAllows to load an icon for the type of Contact
LocationIndicates the position of the typology compared to other existing typologies
Groups EnabledIndicates the groups enabled to create Contacts of this type
StateIndicates status(Enabled/Disabled)

4 – When the fields have been completed, click Save.The new type of Contact will be present in the CRM

Opportunity Types in CRM

The following guide deals with the creation of a customized Type of Opportunity, in addition to those already present in the system.

1 – Open the system configuration for the Types of Opportunities, via System-> CRM Configuration -> Types of Opportunities

2 – Click Add Typology Opportunities

3 – Below is the standard Insert form

The meaning of the fields is as follows:

CampDescription
NameThe name of the typology of Opportunity
LocationIndicates the position of the typology compared to other existing typologies
DescriptionIndicates the description of the type of Opportunity
IconAllows to load an icon for the type of Opportunity
Groups EnabledIndicates the groups enabled to create Opportunities of this type
StateIndicates status(Enabled/Disabled)

4 – When the fields have been completed, click Save.The new type of Opportunity will be present in the CRM

CRM Lists

In the various models present in the CRM are included several fields of list type, an example is the Source of the Contacts of the CRM.

All these lists are present in the system configuration, and therefore are freely customizable.
Please Note: The article superficially deals with the issue of list management. To find out more, see the appropriate section of the Academy.

Here are the lists used for the various models:

  • Account
    • Industry(crm_account_industry): Reference Account Sector
    • Type(crm_account_type): The type of Account
    • Satisfaction(crm_account_satisfaction): The Customer Account Satisfaction Level
  • Contact
    • Rating(crm_contact_rating): The evaluation of the Contact
    • Source(crm_contact_source): The source of the contact, so how it was obtained
  • Opportunity
    • Business Type(crm_opportunity_business_type): The type of Opportunity
    • Source(crm_opportunity_source): The Source of Opportunity
    • Loss Reason(crm_opportunity_loss): Indicates the motivation that led to the eventual loss of opportunity
    • Status(crm_opportunity_business_status): Indicate The custom status of Opportunity_status

Lists are editable in System->Configuration->Tools->Lists

Sync Contacts and Accounts

In the CRM there are the forms Contacts and Accounts, these are not synchronized automatically. This is possible through the synchronization functionalities.

In the CRM – Account module, a Sync Company button is included:  Pressing this button will automatically sync the account with a Company. This synchronization does not automatically keep non-standard fields synchronized.

In the CRM – Contact module, the following buttons are available:

  • For Leads, Convert to Contact to convert to Contact
  • For Leads, Sync User to convert to Deepser User, and keep it in sync

Address Functioning

In Deepser, Addresses can be understood as actual places, companies, or accounts.

The use of Addresses, for example, allows us to manage a company’s Multi-Locations.

  1. In this case, let’s take the Addresses of an account as an example.
    To access this area, click on Crm->Account.

2. Select the account to add its addresses.

3. Select the Address option in the grid on the left.

4. After that, the following screen will appear.

Here you will find the address data related to the main account.

 

Below is a brief explanation of the fields displayed in the form.

Field

Description

Billing Address

Billing Address

Billing City

Billing City

Billing Zip Code

Postal code of the billing city

Billing State

Billing Country

Billing Country

Billing Country

Shipping Address

Shipping Address

Shipping City

Shipping City

Shipping Zip Code

Postal code of the shipping city

Shipping State

Shipping Country

Shipping Country

Shipping Country

 

5. To save your changes, click Apply or Save to save them.

Below is a detailed description of the available buttons:

1 – To return to the previous page without saving.

2 – To reset the information to the last save.

3 – To delete the entered record.

4 – To save and return to the main grid.

5 – To save and stay on the current page.

6 – To synchronize Account -> Company (Present only if the Sync function is enabled).

 

 

6. At the bottom of the Form there is an Address Grid Field (custom fields), in this case ‘Sales Addresses‘, in which you can enter different addresses of companies connected to the main one.

For example, a common use of Addresses is the management of multi-locations, detachments, branches, etc.

7. To add a new address, click the blue Add Address button in the top right corner.

8. The following screen will appear.

Below is a brief description of the fields in the form.

Field

Description

Company Name

Name of the venue

Company Code

Company Code

Address

Address

Zip Code

Postal code

Country

State

Is Default

If there are multiple adresses associated with the company, only one can be designated as the default.

It will be suggested as the default address for address fields in CRM Sales modules.

Status

Set to ‘Enabled‘ to enable it

9. To save, press Apply in the top right corner.

The new address entered, after saving, will be added to the grid below.

Sales

Sales module is located inside CRM module and is used to keep record of sales department. This module has different entities such as quotes, orders, invoices and shipments. 

Quotes

Quotes is an entity inside the sales (1) module and is used to create different quotes based on the products that the client requires.

On the right side we have:

  • the button to create a new quote (2).
  • the grid with all present quotes (3).

Add quote

Add quote is used to create a new quote and has a default form that can be modified to the user’s needs. On the left side (2) we have a menu for different sections of the form.

On the right side we have the form data that will be populated with quote data.

Some of the visible fields are:

  1. Main data:
    • Account -> account related to this quote.
    • Name -> name of the quote.
    • Status -> status of the quote (accepted, draft, rejected à other values can be added in this list)
    • Currency -> currency on which the products price will be calculated.
    • Price list -> shows the list of prices that is associated with this quote.
  2. Payment:
    • Payment condition
    • Billing address
  3. Invoice:
    • Invoice is a grid that contains the invoices created from this quote. You can add, modify, and delete invoices directly from here.

After filling the data and saving, we will see these new fields on the Quote form:

 

  1. We have the button on the right top to create an order based on this quote and with the given products. This will create a record on the Order entity of the Sales module.
  2. It is the grid that displays the products added to this quote. You can add more or delete the selected ones. The products are retrieved from the Catalog

Order

Order is another entity inside Sales (1) and is used to:

  • Manage orders that are created from the quotes entity
  • Create a new order without a quote relation. You can do it by clicking the Create order button and selecting the order type you want it to be (2). Below the button, there’s the grid that displays all available orders.

Add order

An order can be created from quote entity or by clicking create new order. If we create it from the quote entity, the quote field will be populated with a link to the quote which this order is created from.

Some of the visible fields are:

  1. Main data
    • Account -> account related to this order.
    • Name -> name of the order.
    • Status -> status of the order (accepted, draft, rejected)
    • Currency -> currency on which the products price will be calculated.
    • Price list -> shows the list of prices that is associated with this order.
    • Quote -> if the order is created from quote this field will be populated with a link that will redirect to respective quote.
  2. Payment
    • Payment condition
    • Billing address
  3. Shipment
    • Shipment grid -> shows all shipment related to this order. You can add, modify, delete shipments from this grid.
  4. Invoice
    • Invoice is a grid that contains the invoices created from this quote. You can add, modify, and delete invoices from here.

After filling the data and saving we will see these new fields on the Order form.

 

  1. On the right top there’s the button to create a shipment for this order.
  2. On the right top there’s the button to create an invoice for this order.
  3. It’s the grid that displays the products added to this order. You can add more or delete the selected ones. The products are retrieved from the Catalog module.
  4. It’s the quote that is related with this order.

 

Invoice

Invoice is another entity inside Sales (1) and is used to manage invoices that are created from the Quote entity or from the Order entity. You can create a new invoice without a quote or order relation. You can do it by clicking the Create invoice button and selecting the invoice type you want it to be (2). Below the button is the grid that displays all available invoices. (3)

Add Invoice

An invoice can be created from Quote entity or Order entity. You can create it also by clicking the Add Invoice button on the top right side.

Some of the visible fields are:

     1. Main data

    • Account -> account related to this invoice.
    • Name -> name of the invoice.
    • Status -> status of the invoice (enabled, disabled)
    • Model alias -> is the model from which the invoice is created from.
    • Model id -> is the id of the entity that created the invoice.
    • Currency -> currency on which the products price will be calculated.
    • Price list -> shows the list of prices that is associated with this order.

     2. Payment

  • Payment condition
  •  Billing address

     3. Activities and Movements

    • Invoice Related Models is a grid relation that contains the activities related to this invoice. You can add, modify, and delete activities from here.
    • Invoice Related Movements is a grid relation that contains all the warehouse movements connected to this invoice.

After filling the data and saving we will see this new fields on the Invoice form:

Invoice Items is the grid that displays the products added to this invoice. You can add more or delete the selected ones. The products are retrieved from the Catalog module.

 

Shipment

Shipment is another entity inside Sales (1) and is used to manage Shipments that are created from the order entity. When you click on the Shipment section from the left menu, the grid with all the shipments that are generated from the orders is shown.

Edit Shipment

Some of the visible fields are:

1. Shipment

 Account -> account related to this shipment.

 Name -> name of the shipment.

 Status -> status of the order (delivered, received, canceled. Other values can be added)

 Shipping Date -> the Date of shipment.

2. Addresses

Billing Address -> you can select the billing address of the shipment.

  •  Items is the grid that displays the products added to this invoice. You can add more or delete the selected ones. The products are retrieved from the Catalog
  •  Order is a link that opens the Order that is related with this shipment.

Mailchimp Integration

The mentioned integration allows you to one-way synchronize contacts between Deepser and Mailchimp.

As a result, it allows you to automate marketing processes and improve customer management.

The operation of this integration therefore allows you to intervene on Mailchimp audiences, allowing the addition, modification and deletion of contacts.

Mailchimp account configuration

To proceed with the configuration, it will be necessary to access to the “Mailchimp” module from the main menu:

From here, you’ll be able to proceed to set up one or more Mailchimp accounts that you want to interact with.

To do this, it will be necessary to click on “+ Add Account” at the top right of the page and we will find ourselves in front of the following screen:

Below are the details of the fields:

Field

Definition

Server Prefix

The server prefix is the starting part of the endpoint URL. For example, to find your server prefix, you must log into your Mailchimp account and look at the URL in your browser. You’ll see something like https://us19.admin.mailchimp.com/; the us19 part is the server prefix.

 

So, you need to set that value into “Server Prefix” field in Deepser.

Token

API keys grant full access to your Mailchimp account.

To generate an API key, follow these steps.

  1. Click your profile icon and choose Profile.
  2. Click the Extras drop-down then choose API keys.
  3. In the Your API Keys section, click Create A Key.
  4. Name your key. Be descriptive, so you know what app uses that key. Keep in mind that you’ll see only this name and the first 4 key digits on your list of API keys.
  5. Click Generate Key.
  6. Once we generate your key, click Copy Key to Clipboard. Save your key someplace secure–you won’t be able to see or copy it again. If you lose this key, you’ll need to generate a new key and update any integration that uses it.
  7. Click Done.

 

So, after copying the token, you can paste it into “Token” field in Deepser.

Cron Expression

To keep your data between Deepser and Mailchimp up to date, you can schedule syncing at predefined intervals via this field.

Mailchimp Username

There is no need to enhance this field. It will be automatically valued when the record is saved if correctly configured.

Email

There is no need to enhance this field. It will be automatically valued when the record is saved if correctly configured.

Status

A field that allows you to enable or disable the mailchimp account in use on Deepser.


Once the system has been correctly configured, using the “Check” button it will be possible to check the correctness of the data entered. The message that determines a correct configuration will be as follows:

After saving, the “Audiences” grid will be displayed which will serve to contain the information synchronized between the 2 systems.

Note: Only once the synchronization process is complete will the information in it be available.

To perform the synchronization, it will be possible to proceed manually by clicking on the “Sync” button. In this case, if you have a lot of information on your account that needs to be synced, it may take some time for it to fully sync.

Alternatively, you can wait for the synchronization schedule to run automatically based on the configuration of the “Cron Expression” field.

The following information is available within an Audience record:

Field

Definition

Name

In this field, you will find the name of the audience synced with Deepser.

Contacts

Within this grid, only contacts that have been synced from Deepser to Mailchimp will be available.

This means that you won’t have any contacts that were previously in Mailchimp.

 

NOTE: Within this grid you will not see the classic Deepser contacts present in the CRM section, but they are contacts linked to the Mailchimp form and can only be viewed through this grid.

Tags

Within this grid, you’ ll see all the Tags in Mailchimp that are synced to Deepser, for the account you set up.

Mailchimp flow configurations

To proceed with the integration with mailchimp on Deepser, you will need to use the flows module for creating your own automations for mailchimp contacts.

In fact, searching among the actions available in the flows, we can find the following:

Check Mailchimp Contact

Through this action, it will be possible to verify the existence of a particular Mailchimp contact present within an account previously configured on Deepser.

In fact, the action in question will return a Boolean value (true/false) that can eventually be used in a conditional block (if, if-else or others).

The following is the information required in this type of block:

Field

Definition

Mailchimp Account

Through this field you can select one of the accounts configured through the “Mailchimp” module.

Mailchimp Audience

Through this field you can select an audience linked to the selected account.

Model

Through this field it will be possible to associate a model through which to carry out the verification. For example, a record of type “Mailchimp Contacts” or a record of type “CRM Contacts.”

Email Field

The following field will be prompted, only if the selected template is different from “Mailchimp Contacts”.

Create or Update Contact

Through this action, you will be able to create or edit a particular Mailchimp contact within an account previously configured on Deepser.

The action in question will allow you to map the fields of the “Mailchimp Contacts” module and another Deepser module (typically a CRM Contact).

The following is the information required in this type of block:

Field

Definition

Mailchimp Account

Through this field you can select one of the accounts configured through the “Mailchimp” module.

Mailchimp Audience

Through this field you can select an audience linked to the selected account.

Model

Through this field it will be possible to associate a model through which to carry out the verification. For example, a record of type “Mailchimp Contacts” or a record of type “CRM Contacts.”

Status

Through this field you can update the status of the contact on mailchimp, i.e. whether he is subscribed to an audience or not.

Field Mapping

Using this multivalue field, you can map the fields between the “Mailchimp Contacts” module and another Deepser module (e.g. “CRM Contacts”).

Tags

Through the field in question, you can add one or more tags to the contact, among those defined and synchronized with Mailchimp.

Tag Change Type

Through this field, you can intervene in updating the tags in the following way:

 

– Override all Tags: To delete the old tags related to the contact and therefore add only those indicated through the “Tags” field.

 

– Add Tag: To add the tags indicated through the “Tags” field without deleting any tags related to the contact.

 

– Remove Tag: To remove tags specified via the “Tags” field from the contact.

NOTE: When a Mailchimp contact is created/edited, the originating pattern used will be tied to the record via a 1:1 relationship. For example, if you create a Mailchimp contact from a CRM Contacts record, the two records CRM Contacts and Mailchimp Contacts will be linked to each other.

Delete Contact

Through this action, it will be possible to delete a particular Mailchimp contact present within an account previously configured on Deepser.

The following is the information required in this type of block:

Field

Definition

Mailchimp Account

Through this field you can select one of the accounts configured through the “Mailchimp” module.

Mailchimp Audience

Through this field it is possible to select the target audience linked to the selected account.

Model

Through this field it will be possible to associate the mailchimp contact template to be deleted or its linked template (e.g. its CRM Contacts used for creation/update).

 

In either case, the deletion will only be done on the Mailchimp contact and never on the linked template.

Delete Type

Through this field, you can intervene to indicate the method of cancellation of the Contact, which can be:

 

– Archive Contact: Which allows you to archive the contact on Mailchimp

 

– Permanent Delete Contact: Which performs a permanent delete on Mailchimp.

 

Deepser API

 

This is an advaced – developer focused – course that aims to teach everything about Deepser’s Rest APIs.

API Notions

Deepser was designed to meet all IT department needs.
The Deepser REST API was designed to meet specific needs for the customization and integration of the software, in particular:

  • Retrieve, store and process data in the best way for your organization
  • Interface and integrate Deepser with third party applications

API REST is natively supported by any version of Deepser.
Before you start reading the guide it is important to know some key concepts, described in this lesson.

API Endpoint and URL

You access the resource by sending an HTTP request to the Deepser API server. The server replies with a response that contains either the data you requested, or the status indicator, or even both.
Common characteristics of Deepser REST API resources are as follows: (deepserhost is your domain)

  • To access the API you have to call the endpoint at: 
http[s]://deepserhost/api/rest/
  • You request a particular resource by adding a particular path to the base URL that specifies the resource.
  • The server replies with a response that contains either the data you requested, or the status indicator, or even both.

REQUEST STRUCTURE

All URLs in REST API have the following base URL.

http[s]://deepserhost/api/rest/

Example:
Supposing you want to retrieve the list of Companies from Deepser.
To do this, you need to use the GET HTTP method.

The GET request to retrieve the list of Companies will look as follows:

http[s]://deepserhost/api/rest/companies

where:

  • http[s]://deepserhost/api/rest is the endpoint
  • /companies is the action URL

UNDERSTANDING ROUTES

Typically, Deepser has 2 main routes for each entity’s action URL.
The first one, we have just seen, is used to retrieve the entity collection, so it is generally the name of the entity in a plural form. For the entity Company it is:

http[s]://deepserhost/api/rest/companies

It must be called using an HTTP GET request and can be followed by filters or parameters (described in the next chapters) to provide the desired selection of the records.
For example, if we want to retrieve only the first Company with name starting with ‘ACME’, we should use this HTTP request to the REST API:

http[s]://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&limit=1

We will explain in the next chapters all the filters and parameters.
To analyze this simple request, we have defined (after the endpoint and the route):

  • filter: an array containing in each element the structure of the filter
  • [attribute]: the element of each filter with the attribute to filter
  • [like]: the element of each filter with the selection type (in our case we want a SQL like)
  • limit: a parameter to limit the response results to just one element

If we want to retrieve a single element (eg: for which we already know the ID) we don’t use the routes to access a collection, but we use the route to get the single entity.
This is typically the name of the entity, followed by the ID of the entity.
In our example we get the company with ID = 4

http[s]://deepserhost/api/rest/company/4

It will retrieve all fields of the company with ID = 4.

API Verbs and Format

HTTP verbs are used to manage the state of resources.
In Deepser REST API there are four verbs used to manage resources: GET, POST, PUT, and DELETE.
You can:

  • Create new entity data using HTTP POST
  • Retrive the contents of the data using HTTP GET
  • Update the data using PUT
  • Delete the data using HTTP DELETE

API AUTHORIZATION

Deepser API uses those methods to get, create, update or delete entities.
Based on the entity, on the role and the permissions of the logged-in user, there are different actions allowed.
The details will be explained in the next chapters, but you must remember the actions implemented by the API are:

  • Create: to create a single resource (HTTP POST)
  • Retrieve: to get a single resource (HTTP GET)
  • Update: to update a single resource (HTTP PUT)
  • Delete: to delete a single resource (HTTP DELETE)
  • Multiple Retrieve: to get multiple resources (HTTP GET)
  • Multiple Create: to create multiple resources (HTTP POST)
  • Multiple Update: : to update multiple resources (HTTP PUT)

Multiple Delete is not allowed for Security Reasons.

API FORMAT

The REST API response is a JSON object, depending on the resource requested.
A brief example (we will describe in the next chapters in details) is the following:

				
					{
   "totalRecords":2,
   "items":[
      {
         "entity_id":"1",
         "parent_id":"0",
         "sort_order":null,
         "name":"ACME International",
         "description":"ACME International – Main Company of the group",
         "phone":"0288396",
         "fax":"998266",
         "address":"Madison Square Garden",
         "city":"NY",
         "state":"NY",
         "country":"USA",
         "zip_code":"00195",
         "notes":null,
         "logo":"company/image/a/c/acme_usa.png",
         "primary_contact":"4\\euclid",
         "mailbox_id":"0",
         "status":"1",
         "formtemplate_id":"56",
         "updated_at":"2018-07-12 08:43:13",
         "created_at":"2018-06-19 13:30:41"
      },
      {
         "entity_id":"2",
         "parent_id":"1",
         "sort_order":null,
         "name":"ACME France",
         "description":"ACME France",
         "phone":null,
         "fax":null,
         "address":"Roux de Strasse",
         "city":"Paris",
         "state":"Paris",
         "country":"France",
         "zip_code":"75000",
         "notes":null,
         "logo":"company/image/a/c/acme_fr_1.png",
         "primary_contact":"4\\euclid",
         "mailbox_id":"0",
         "status":"1",
         "formtemplate_id":"56",
         "updated_at":"2018-07-12 08:43:56",
         "created_at":"2018-06-19 13:33:57"
      }
   ]
}
				
			

API Authentication

If you want to use Deepser API you must authenticate before using it.
The authentication supported by Deepser are currently of 2 types: the Basic Authentication and the Authentication with Token. We strongly suggest to use Token Authentication for improved security.


AUTHENTICATION WITH TOKEN

This can be done, before any request to the API, with some simple lines of code to add the Authentication parameters to the HTTP Headers.
In addition to the Basic Authentication, you have also to enable the Token for the user you want to authenticate.
To do that, you have to login into Deepser as a System Admin.
Go to the Configuration for the User you want to enable to token Authentication through API.
The menu in Deepser is System > Permissions > Users and then select the user you need to enable for token authentication.

PLEASE NOTE: If the “API Token” field isn’t visible, expose it by pressing the edit form button.

Then expose the field by using drag and drop.

You can use the three buttons to perform automatic actions on the Token: generate, delete or copy to clipboard.

From a developer’s perspective, once enabled the Token for the User, you need to set the header of the HTTP Request with the token.
In the following example, we see how to add the authentication parameter to a CURL request in PHP language:

				
					$host = 'http://deepserhost';
$process = curl_init($host);
$token="DEMO_TOKEN";
$headers = array(
'Authorization: Bearer '. $token,
'Accept: application/json'
);
curl_setopt($process, CURLOPT_HTTPHEADER, $headers);
// other lines to set the API request
…
// call the API using CURL
$return = curl_exec($process);
curl_close($process);
				
			

Where http://deepdeskhost is the address of your Deepser and token is the token generated for the user.

BASIC AUTHENTICATION

This can be done, before any request to the API, with some simple lines of code to add the Authentication parameters to the HTTP Headers.
To achieve that we need to set the header with the string ‘username’:’password’ encoded in base64 format.
In the following example, we see how to add the authentication parameter to a CURL request in PHP language:

				
					$host = 'http://deepserhost';
$process = curl_init($host);
$headers = array(
      'Authorization: Basic '. base64_encode("user:password")
);
curl_setopt($process, CURLOPT_HTTPHEADER, $headers);
// other lines to set the API request
…
// call the API using CURL
$return = curl_exec($process);
curl_close($process);
				
			

Where http://deepserhost is the address of your Deepser and user:password is your username/password.

Of course, if you prefer to use other languages, the REST technology is language-independent.
We see how to use Java to make such a call:

				
					String encoding = Base64Encoder.encode ("user:password");
HttpPost httppost = new HttpPost("http://deepserhost");
httppost.setHeader("Authorization", "Basic " + encoding);
// other lines to set the API request
…
// call the API using Java HttpRespnse
HttpResponse response = httpclient.execute(httppost);
HttpEntity entity = response.getEntity();
				
			

Now that you know how to authenticate to Deepser API, go to the next lesson to see the advanced documentation of the API.
We assume you have already read the API introduction and you have learnt all the basic concepts stated in that guide.

API Main Methods

You can access entities of Deepser, using the actions implemented by the API:

    • Create: to create a single resource (HTTP POST)
    • Retrieve: to get a single resource (HTTP GET)
    • Multiple Retrieve: to get multiple resources (HTTP GET)
    • Update: to update a single resource (HTTP PUT)
    • Delete: to delete a single resource (HTTP DELETE)

Note: Multiple Delete is not allowed for Security Reasons.

We will now explain in details every action.
In this lesson the examples are all made using the Company entity.
We assume your Deepser installation host is http://deepserhost/.
After having explored the methods, we will list a detail of entities accessible by the API.

Retrieve

HTTP Method: GET
Base Syntax:

http://deepserhost/api/rest/[entity]/[id]

Example Syntax:

http://deepserhost/api/rest/company/4

Description: retrieves the entity data, given an entity ID.
Example Result:

http://deepserhost/api/rest/company/4
				
					{
    "entity_id": "4",
    "parent_id": "1",
    "sort_order": null,
    "name": "ACME UK",
    "description": "ACME UK",
    "phone": "08567565",
    "fax": "8587575",
    "address": "Carnaigehall Street",
    "city": "London",
    "state": "London",
    "country": "UK",
    "zip_code": "10000",
    "notes": null,
    "logo": "company/image/a/c/acme_uk.png",
    "primary_contact": "4\\nobel",
    "mailbox_id": "0",
    "status": "1",
    "formtemplate_id": "56",
    "updated_at": "2018-08-01 15:04:59",
    "created_at": "2018-07-12 08:39:16",
}
				
			

Note that every custom field created in Deepser is retrieved by the API. Custom fields have the prefix cust_ before their name.
So, for example, if a user creates a field named website, the REST API will return a JSON property called cust_website.

Multiple Retrieve

HTTP Method: PUT
Base Syntax:

http://deepserhost/api/rest/[entities]?[filters]&[parameters]

Example Syntax:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&limit=2

Description: retrieves the entities data, given some filters or parameters.
Example Result:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&limit=2
				
					{
    "totalRecords": 3,
    "items": [
        {
            "entity_id": "1",
            "parent_id": "0",
            "sort_order": null,
            "name": "ACME International",
            "description": "ACME International - Main Company of the group",
            "phone": "0288396",
            "fax": "998266",
            "address": "Madison Square Garden",
            "city": "NY",
            "state": "NY",
            "country": "USA",
            "zip_code": "00195",
            "notes": null,
            "logo": "company/image/a/c/acme_usa.png",
            "primary_contact": "4\\euclid",
            "mailbox_id": "0",
            "status": "1",
            "formtemplate_id": "56",
            "updated_at": "2018-07-12 08:43:13",
            "created_at": "2018-06-19 13:30:41",
            "payment_status": null
        },
        {
            "entity_id": "2",
            "parent_id": "1",
            "sort_order": null,
            "name": "ACME France",
            "description": "ACME France",
            "phone": null,
            "fax": null,
            "address": "Roux de Strasse",
            "city": "Paris",
            "state": "Paris",
            "country": "France",
            "zip_code": "75000",
            "notes": null,
            "logo": "company/image/a/c/acme_fr_1.png",
            "primary_contact": "4\\euclid",
            "mailbox_id": "0",
            "status": "1",
            "formtemplate_id": "56",
            "updated_at": "2018-07-12 08:43:56",
            "created_at": "2018-06-19 13:33:57",
            "payment_status": null
        }
    ]
}
				
			

Where:

totalRecords is the number of items corresponding to the conditions of the query (note that is more than the limit we set).
items is a JSON array with all entities retrieved (eventually limited to the limit parameter).

FILTERS
When we deal with the multiple retrieve method, it is important to understand filters and parameters to get only a subset of data if we don’t need to retrieve all the entities of the system.

Think about filters as the where condition of a SQL Query, while parameters are clauses (limit, sort, etc.) for that query.
Deepser API filters are very simple to implement.
To define filters, just pass additional fields to the HTTP request query string.
The syntax to define filters is here described.
After the request path we define an array called filter.
This array has at least one element with key attribute to define the target field:

http://deepserhost/api/rest/companies?filter[1][attribute]=field

Where:

  • filter is our array to set filters
  • attribute is a constant key
  • field is the name of the field we want to apply the filter to

Then, we must define which kind of filter we want to apply to that field, by populating in the query string the element of the filter array with key corresponding to the kind of filter. The value of that element is the value to look for:

http://deepserhost/api/rest/companies?filter[1][attribute]=field&filter[1][operator]=value

Where:

  • filter is our array to set filters and the index 1 is the same of the attribute field we are referring to
  • operator is a key with the query operator we want to apply. Operators are described below
  • value is the value of the condition we want to apply to the filter

To filter a company by its name, taking all the companies with name starting with the string ‘ACME’, we should raise this GET request:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%

Obviously, to implement more filters on different fields we can add more elements to our filter array:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&filter[2][attribute]=country&filter[2][eq]=USA

This will filter all companies with name starting with ACME and country equals to USA.

FILTER OPERATORS

When we deal with filters, it is important to understand filter operators to create the query we need.
Here is a list of all operators that can be used:

  • eq – “equal to” – returns items with the specified attribute that is equal to the defined value
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%
  • neq – “not equal to” – returns items with the specified attribute that is not equal to the defined value
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][neq]=ACME
  • in – “equals any of” – returns items that are equal to the item(s) with the specified attribute(s)
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][in]=ACME

If we want to use multiple values for the in, we can use an additional array, so for example:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][in][0]=ACME&filter[1][in][1]=Contoso 
  • nin – “not equals any of” – returns items excluding the item with the specified attribute
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nin][1]=ACME&filter[1][nin][2]=International
  • gt – “greater than” – returns items with the specified attribute that is greater than the defined value
http://deepserhost/api/rest/companies?filter[1][attribute]=parent_id&filter[1][gt]=0
  • lt – “less than” – returns items with the specified attribute that is less than the defined value
http://deepdeskhost/api/rest/companies?filter[1][attribute]=parent_id&filter[1][lt]=1
  • like – “like” – returns items with the specified attribute is like the defined value. Use SQL like syntax to define wildcards chars.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%
  • nlike – “not like” – returns items with the specified attribute is not like the defined value. Use SQL like syntax to define wildcards chars.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%
  • from, to – “from to” – specifies the range of attributes according to which items will be returned.
http://deepserhost/api/rest/companies?filter[1][attribute]=parent_id&filter[1][from]=2&filter[1][to]=3

You can write filters using AND, OR logical operators.
To do that follow the examples:

  • AND: to define a condition in AND, simply define multiple filters, like:
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&filter[2][attribute]=parent_id&filter[2][gt]=0
  • OR: to define a condition in OR, use this syntax:
http://deepserhost/api/rest/companies?filter[1][attribute]=entity_id&filter[1][0][eq]=1&filter[1][1][eq]=3

So use multiple index arrays in the filters for the same field.

To use an OR condition on different fields, use the following syntax:

http://deepserhost/api/rest/companies?filter[1][attribute]=entity_id&filter[1][0][eq]=1&filter[1][1][eq]=3

PARAMETERS

When we deal with retrieve multiple method, it is important to understand parameters to create the query we need.
Here is a list of all parameters that can be used:

  • page: specifies the page number which items will be returned.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%&page=2
  • order: specifies the sort order of returned items.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%&order=name&dir=asc
  • dir: specifies the order direction: ‘asc’ – returns items in the ascending order; ‘dsc’ – returns items in the descending order.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%&order=name&dir=asc
  • limit: limits the number of returned items in the response. Note that by default, 10 items are returned in the response. The maximum number is 100 items.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%&limit=100

If the attribute value consists of several words separated by a whitespace, the ‘%20’ sign is used:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][eq]=ACME%20International%20LTS

Create

HTTP Method: POST
Base Syntax:

 http://deepserhost/api/rest/[entities]/

JSON Payload Syntax: a JSON object with the data to insert

Example Syntax:

http://deepserhost/api/rest/companies

Example JSON Payload Syntax:

				
					{
    "name" : "ACME Portugal",
    "description" : "ACME Portugal SA."
}
				
			

Description: creates the entity, given the payload JSON data.
Example Result:

http://deepserhost/api/rest/companies
				
					{
    "name": "ACME Portugal",
    "description": "ACME Portugal SA.",
    "created_at": "2018-10-29 15:57:42",
    "updated_at": "2018-10-29 15:57:42",
    "entity_id": "8"
}
				
			

Returns the company created, field entity_id is the ID of the new company.

Update

HTTP Method: PUT
Base Syntax:

http://deepserhost/api/rest/[entity]/[id]

JSON Payload Syntax: a JSON object with the data to update

Example Syntax:

 http://deepserhost/api/rest/company/5

Example JSON Payload Syntax:

				
					{
    "name" : "ACME Germany",
    "parent_id" : "1",
    "description" : "ACME Germany Gmbh"
}
				
			

Description: creates the entity, given the payload JSON data.
Example Result:

http://deepserhost/api/rest/companies
				
					{
    "entity_id": "5",
    "parent_id": "1",
    "sort_order": null,
    "name": "ACME Germany",
    "description": "ACME Germany Gmbh",
    "phone": null,
    "fax": "+498587575",
    "address": "Augsburger Strasse",
    "city": "Berlin",
    "state": "Berlin",
    "country": "DE",
    "zip_code": "10115",
    "notes": null,
    "logo": null,
    "primary_contact": null,
    "mailbox_id": "0",
    "status": "1",
    "formtemplate_id": "0",
    "updated_at": "2018-10-29 16:14:10",
    "created_at": "2018-10-29 15:49:33",
    "payment_status": null
}
				
			

Returns a JSON Object with all fields of the entity updated (not only updated fields, but ALL fields of that entity).

Delete

HTTP Method: DELETE
Base Syntax:

http://deepserhost/api/rest/[entity]/[id]

Example Syntax:

http://deepserhost/api/rest/company/6

Description: deletes the entity, given an entity ID.
Example Result:

http://deepserhost/api/rest/company/6
				
					// this is only in case of an error
{
    "messages": {
        "error": [
            {
                "code": 404,
                "message": "Resource not found."
            }
        ]
    }
}
				
			

If the entity is successfully deleted returns an empty response, else returns a JSON object with error messages.

API Entities

Here you are the full list of Deepser entities implemented by the API:

  • Company: the companies of Deepser.
  • User: the users of Deepser.
  • Group: the user groups of Deepser.
  • Service Operation: the operations (tickets, incidents, requests, etc.) of Deepser.
  • Service Type: the types of the operations (incidents, requests, changes, phone calls, etc.).
  • Activity: the activities (comments or worklogs) of Deepser.
  • Cmdb CI: the CIs (devices, softwares, etc.) of Deepser.

API Company

The Company entity is used to manage companies in Deepser.
Companies can be only created by Administrators that can access the Company Module.
Agents and Key Users can only retrieve the Companies.
End Users cannot access this resource via API.

Endpoints

http://deepserhost/api/rest/company/[id]
http://deepserhost/api/rest/companies

Roles

Here we list all the permissions by user role regarding the API:

 AdmininistratorAgentKey UserUser
Actions AllowedRETRIEVE
CREATE
UPDATE
DELETE
RETRIEVERETRIEVE 

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

FieldMeaning
entity_idThe unique ID to identify the record.
nameThe name of the Company, that will be displayed on the select-boxes in the system.
parent_idThe field “Parent” can contain the name of another company. If the Company has a parent, it means that we are configuring a sub-company (a branch of the main company). Think about an international corporation that has some local branches (eg: the head office is in the US and some branches in Europe). Thank to the Parent field we can create a hierarchical structure of maximum 2 levels to define companies in the system. The Parent concept can be eventually extended to more levels with a customization but the default configuration of Deepser allows 2 levels: in most cases it is enough to describe a company structure.
If we try to add more than 1 Parent level, the software returns a blocking error in the company form.
descriptionDescription of the Company.
statusIf the company is disabled it will not be displayed in the select-boxes.
mailbox_idThis field is used to define that all the emails sent to users of that organization will be sent by a specific mailbox.
This field is rarely used and has the aim to send emails to a specific company from a pre-configured email address. If not set Deepser will use the system settings to send emails: the emails will be sent from the default outgoing mailbox, or, if the record has a specific mailbox set in the field “Outgoing Mailbox”, Deepser will use the specific mailbox only for that records.
logoCompany Logo.
addressCompany Address.
cityCompany City.
stateState / Area.
countryCountry of the company.
zip_codeZip Code.
primary_contactUser of Deepser that is marked as a primary contact for that company.
phoneMain phone number.
faxFax.
notesInternal notes.
formtemplate_idThe form template ID used by the record. Please refer to the Formtemplate ID guide of Deepser Docs.
updated_atLast update date of the record.
created_atThe creation date of the record.

User API

The User entity is used to manage users that can login to Deepser.
Users can be only created by Administrators that can access the User Module.
Agents and Key Users can only retrieve the Users.
End Users cannot access this resource via API.

Endpoints

http://deepserhost/api/rest/user/[id]
http://deepserhost/api/rest/user/[id]

Roles

Here we list all the permissions by user role regarding the API:

 AdmininistratorAgentKey UserUser
Actions AllowedRETRIEVE
CREATE
UPDATE
DELETE
RETRIEVERETRIEVE 

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

FieldMeaning
user_idThe unique ID to identify the record.
avatarIcon with the user avatar. If not set, it will be chosen randomly from the system.
usernameUsername used by a user to access the software. It is the field that uniquely identifies the user.
Username is thus used for the login to Deepser. If we create manually a user, we can choose the username we want.
Obviously, user name must be unique otherwise the system will block the creation of a user with a username already in use.
If we insert users with the LDAP integration the username will be the LDAP attribute we chose when configuring the integration, but Deepser prepend a number and a backslash (\) to identify the ID of the LDAP directory from which we are importing the user.
In case of LDAP users, the login screen of Deepser will change, adding a select-box to choose the domain. This select-box is thus mandatory for the users with an LDAP account.
A user manually inserted has, for example, this username: admin or name.surname, or rather the email of the user.
A user imported from LDAP will have, for example, this username: 1\name or 1\name.surname.
Looking at the ID of the LDAP directory we can easily find from which LDAP source the user has been imported.
roleThe role of the user. Please refer to the Roles in your system to get the correct IDs.
firstnameFirst name of the user
lastnameLast name of the user
emailEmail of the user to receive notifications. Email is a very important field if we activate the email integration: Deepser send all the emails to users according to this value.
passwordPassword to log into the system. Password is encrypted in the database. If a user is an LDAP user the password will not be saved in the database, but the system will try to authenticate directly to the LDAP server.
is_activeIt tells if an user is active in the system. Non-active users are not displayed in the select-boxes of Deepser modules, cannot receive emails and cannot log into the system.
startup_pagePage to which the user is redirected after the login. This field contains a list of all the system pages.
localeLanguage of the user. Deepser has a native support to many languages. It is possibile to translate the software using this short guide: Translate Deepser
timezoneTimezone of the user. Timezone is applied when displaying the dates on the interface. Infact, in the Deepser DataBase all dates are stored referring to the system timezone: UTC. This setting allows the system to manage all the dates with consistency and not to have problem with the variaton of dates based on the location of a user.
company_idCompany of the user. All users can be part of one (and only one) company. Companies are explained in that guide: Company Guide.
Companies can be grouped in a 2 level structure: one company is the Parent and can have multiple sub-companies. That way we can manage the visibility of the requests allowing, for example, a corporate manager to see all the sub-company requests and allowing a director of a sub-company to see only data of his smaller organization.
is_supervisorIf the user is a supervisor he can see data of all users of the company (and sub-companies). This field is very important to determine which data cha see a user within his organization. If the user is a supervisor and can access the back-end (Administrator, Agent, Key-User) he can see all data of his Company and sub-companies. This is true if the user has the field Company Visibility set to Limit Data to Company. On the contrary, the user can see all data in the system.
If we talk about a user with type “User” (an end user/customer), this user can only see the data regarding his requests (and no other). But, if the user is configured as supervisor can see all the Service Operations of his Company (and sub-companies if present).
company_visibilityA user with this field set can see only data of his company (and sub-companies). If a user access the back-end this field is very useful to limit the visibility. Think, for example, to an operator that can only manage requests from his brach. If we create a company specifically for the branch and limit the data of the user to that branch, the operator will not see any other company data.
Talking about a user of type “User” this field is always ignored, because the user can only see his records and if the field Is Supervisor is set to true, then he can also see the data of his company.
formtemplate_idThe form template ID used by the record. Please refer to the Formtemplate ID guide of Deepser Docs.
modifiedLast update date of the record.
createdThe creation date of the record.
display_usernameThe username displayed in the system (typically Firstname + Lastname).

Group API

The Group entity is used to manage user groups in Deepser.
Groups can be only created by Administrators that can access the Group Module.
Agents and Key Users can only retrieve the Groups.
End Users cannot access this resource via API.

Endpoints

http://deepserhost/api/rest/group/[id]
http://deepserhost/api/rest/groups
http://deepserhost/api/rest/group/[id]/relation/users

Roles

Here we list all the permissions by user role regarding the API:

 AdmininistratorAgentKey UserUser
Actions AllowedRETRIEVE
CREATE
UPDATE *
DELETE
RETRIEVERETRIEVE 

* UPDATE not allowed for endpoint:

http://deepdeskhost/api/rest/group/[id]/relation/users

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

FieldMeaning
entity_idThe unique ID to identify the record.
nameThe name of the group displayed in the system.
descriptionDescription of the group.
emailEmail address of the group.
levelSupport level of the group
statusThe status of the group. Typically 1 is Enabled, 0 is Disabled.
company_visibilityThis is similar to company_visibility of the Users. This is a general setting used to set the visibility for all members of the group.
user_idsAn Array containing all the users of the group.
formtemplate_idThe form template ID used by the record. Please refer to the Formtemplate ID guide of Deepser Docs.
updated_atLast update date of the record.
created_atThe creation date of the record.

To get only the users in a group (without all the group information) you must use the GET method with the endpoint:

http://deepserhost/api/rest/group/[id]/relation/users

It returns an array with the IDs of the users.

To add users in a group you must use the POST method with the endpoint:

http://deepserhost/api/rest/group/[id]/relation/users

JSON Payload Syntax: a JSON array with an array of the data to insert

				
					[
    [
        21,
        22
    ]
]
				
			

To delete users from a group you must use the DELETE method with the endpoint:

http://deepserhost/api/rest/group/[id]/relation/users

JSON Payload Syntax: a JSON array with an array of the data to delete

				
					[
    [
        21,
        22
    ]
]
				
			

Service Operation API

The Service Operation entity is used to manage Operations (tickets) in Deepser.
Service Operations can be accessed by every user.

Endpoints

http://deepserhost/api/rest/service/operation/[id]
http://deepserhost/api/rest/service/operations

Roles

Here we list all the permissions by user role regarding the API:

 AdmininistratorAgentKey UserUser
Actions AllowedRETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

FieldMeaning
entity_idThe unique ID to identify the record.
type_idThe Type ID of the operation record (it is the numerical ID of the entity type: incident, request, change, etc.).
titleThe title of the operation. A brief description.
category1The category (1st level) of the operation. It is an important field to manage the assignment to working teams and to catalog correctly the scope of the activity requested.
category2The category (2nd level) of the operation. It is an important field to manage the assignment to working teams and to catalog correctly the scope of the activity requested.
category3The category (3rd level) of the operation. It is an important field to manage the assignment to working teams and to catalog correctly the scope of the activity requested.
descriptionExtended description of the request.
statusIt is the status of the operation. It is an important value to manage the lifecycle of the request.
priority_idPriority of the operation: the importance from the working team perspective.
urgency_idUrgency of the operation: the importance from the requester user perspective.
submit_usernameThe user that has created the record (he can be different from the Requester User that is the user actually requesting an activity). Think about a secretary that is submitting a request on behalf of his boss. The Submit User is the secretary, while the Requester User is the chief officer.
requester_usernameUser that is actually requesting a service.
assigned_group_idWorking team that is working to solve the request.
assigned_usernameUser that has taken in charge the request. He is typically an Agent or a Key User. Deepser lets you assign also to end users if we decide that they can be part of the resolution process.
created_atCreation date of the record.
updated_atDate of the last update on the system.
closed_atClosing date of the record. If a record changes status from closed to re-opened, the this date is reset to null.
archivedEvery Operation can be archived, for example we can archive all closed Operations of the past 5 years to hide them in the standard grids (but we could see them in the Archived grid).
archived_atArchived date of a request.
updated_byThe user that has lat updated the request.
deletedEvery Operation can be deleted setting the status to “Deleted” (or other status belonging to the Deleted class). All deleted requests will not be physically deleted from the database, but they will be only marked as deleted (soft delete, so they will be visibile in the Deleted grid). To delete physically use the button “Delete”. The record will not be recoverable anymore.
deleted_atDeleted date of the request.
mailbox_idThe mailbox that will be used to send notifications regarding the Operation. If empty the default outgoing mailbox will be used (if set).
due_dateThe agreed date for the resolution.
versionThe version of the request. Deepser stores in its DataBase every version of the Operations. We can always know the changes, the user that made a change and the date.
solutionThe solution of a request, that can be emailed to the requester user or exposed on the portal.
formtemplate_idThe formtemplate id of the record.

Service Type API

The Service Type entity is used to manage the type of Operations in Deepser (eg: Incidents, Tickets, Requests, Phone Calls, etc.).
Service Types can be defined or updated only in the Deepser interface.
Service Types can be only retrieved by Administrators, Agents or Key Users via API.
End Users cannot access this resource via API.

Endpoints

http://deepserhost/api/rest/service/type/[id]
http://deepserhost/api/rest/service/types

Roles

Here we list all the permissions by user role regarding the API:

 AdmininistratorAgentKey UserUser
Actions AllowedRETRIEVERETRIEVERETRIEVE 

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

Here we list all the fields of the entity to describe their meainings in Deepser:

FieldMeaning
entity_idThe unique ID to identify the record.
nameThe Name of the Type (eg: Incident, Request, Change, etc.).
descriptionThe description of the Type.
iconThe icon of the Type.
positionThe order in which are displayed the Types.
status1 if the Type is Enabled, 0 if it is Disabled.
formtemplate_idThe formtemplate ID of the record.
created_atCreation date of the record.
updated_atDate of the last update on the system.

Activity API

The Activity entity is used to manage all the comments and worklogs in Deepser.

Activities can be accessed by all user Roles in the API.

Activities API access changes based on the Main Model (model_alias) the Activity is referring to.

Activity entities are supported for these models:

Model name

Model alias

Operation

deep_service/operation

Account

deep_crm/account

Device

deep_asset/device

Quote

deep_sales/quote

Contract

deep_contract/contract

Ci

deep_cmdb/ci

 

GET Endpoint

This endpoint retrieves the entity data that has the specified values.

 

For this endpoint we have 3 mandatory fields:

  • activity_id, that contains the id of the activity I want to retrieve.
  • model_alias, that contains the model that relates to that specific activity.
  • model_id, that contains the id of the model that this activity relates to.

 

 

HTTP Method: GET
Base Syntax:

				
					http://deepserhost/api/rest/activity/activity/[activity_id]?model_alias=[model_alias]&id=[model_id]
				
			

Example Syntax:

				
					http://deepserhost/api/rest/activity/activity/234?model_alias=deep_service/operation&id=196
				
			

Example Result:

				
					http://deepserhost/api/rest/activity/activity/234?model_alias=deep_service/operation&id=196
				
			
				
					{
    "entity_id": 129,
    "type": 1,
    "description": null,
    "portal_visibility": 0,
    "frontend_visibility": 0,
    "started_at": null,
    "ended_at": null,
    "duration": null,
    "contract_id": 0,
    "contract_line_id": 0,
    "contract_line_qty": "0.0000",
    "created_by": "admin",
    "model_alias": "deep_service/operation",
    "model_id": 90,
    "status": null,
    "formtemplate_id": 0,
    "disable_routing": 0,
    "updated_at": "2023-07-05 08:55:49",
    "created_at": "2023-07-05 08:55:49"
}
				
			

PUT Endpoint

This endpoint updates the entity data specified in the body of the request as JSON that has the specified values.

 

For this endpoint we have 3 mandatory fields:

  • activity_id, that contains the id of the activity I want to update.
  • model_alias, that contains the model that relates to that specific activity.
  • model_id, that contains the id of the model that this activity relates to.

 

HTTP Method: PUT
Base Syntax:

				
					http://deepserhost/api/rest/activity/activity/[activity_id]?model_alias=[model_alias]&id=[model_id]
				
			

Example Syntax:

				
					http://deepserhost/api/rest/activity/activity/234?model_alias=deep_service/operation&id=196
				
			

Example Syntax:

				
					http://deepserhost/api/rest/activity/activity/234?model_alias=deep_service/operation&id=196
				
			

Body of the request:

				
					{
    "description": "Test Description"
}

				
			

Please make sure that the key of the JSON data matches the field code of the entity that you want to update otherwise it will not be updated. In this case we will update the description field of this entity.

The response of this API call will be the updated version of the entity.

				
					{
    "entity_id": 128,
    "type": 2,
    "description": "Test Description",
    "portal_visibility": 0,
    "frontend_visibility": 0,
    "started_at": "2023-02-07 11:15:00",
    "ended_at": "2023-02-07 12:30:00",
    "duration": 4500,
    "contract_id": 1,
    "contract_line_id": 1,
    "contract_line_qty": "0.0000",
    "created_by": "demo.key.user",
    "model_alias": "deep_service/operation",
    "model_id": 90,
    "status": 1,
    "formtemplate_id": 45,
    "disable_routing": 0,
    "updated_at": "2023-07-05 08:28:45",
    "created_at": "2023-02-07 11:34:00"
}

				
			

POST Endpoint

This endpoint creates a new Activity entity with data given in the body of the request as JSON that has the specified model_alias and operation_id.

 

For this endpoint we have 2 mandatory fields:

  • model_alias, that contains the model that relates to the activities I want to create.
  • model_id, that contains the id of the model that this activity will relate to.

 

 

HTTP Method: POST
Base Syntax:

				
					http://deepserhost/api/rest/activity/activities?model_alias=[model_alias]&id=[model_id]
				
			

Example Syntax:

				
					http://deepserhost/api/rest/activity/activities?model_alias=deep_service/operation&id=196
				
			

Example Result:

				
					http://deepserhost/api/rest/activity/activities?model_alias=deep_service/operation&id=196
				
			

Body of the request:

				
					{
    "type": 1,
    "description": "Test Description",
    "portal_visibility": 0,
    "frontend_visibility": 0
}

				
			

Please make sure that the keys of the JSON data match the field codes of the entity that you want to create otherwise the entity will be created with only the corresponded fields. In this case we will create a new Activity with the given data in the body of the request.

 

The response of this API call will be the updated version of the entity.

				
					{
    "type": 1,
    "descritpion": "Test Description",
    "portal_visibility": 0,
    "frontend_visibility": 0,
    "model_alias": "deep_service/operation",
    "model_id": 90,
    "created_by": "admin",
    "created_at": "2023-07-05 09:00:30",
    "updated_at": "2023-07-05 09:00:30",
    "entity_id": 130
}

				
			

DELETE Endpoint

 

This endpoint Deletes the entity that has the specified activity_id, model_alias, model_id.

 

For this endpoint we have 3 mandatory fields:

  • activity_id, that contains the id of the activity I want to delete.
  • model_alias, that contains the model that relates to that specific activity.
  • model_id, that contains the id of the model that this activity relates to.

 

 

HTTP Method: DELETE
Base Syntax:

				
					http://deepserhost/api/rest/activity/activity/234?model_alias=deep_service/operation&id=196
				
			

Example Syntax:

				
					http://deepserhost/api/rest/activity/activities?model_alias=deep_service/operation&id=196
				
			

Example Result:

				
					http://deepserhost/api/rest/activity/activity/234?model_alias=deep_service/operation&id=196
				
			

This method doesn’t return any response.

 

 

Load multiple entities Endpoint

This endpoint retrieves all entities that have the specified model_alias and model_id.

 

For this endpoint we have 2 mandatory fields:

  • model_alias, that contains the model that relates to the activities I want to retrieve.
  • model_id, that contains the id of the model that these activities relate to.

 

HTTP Method: GET
Base Syntax:

				
					http://deepserhost/api/rest/activity/activities/?model_alias=[model_alias]&id=[model_id]
				
			

Example Syntax:

				
					http://deepserhost/api/rest/activity/activities/?model_alias=deep_service/operation&id=196
				
			

Example Result:

				
					http://deepserhost/api/rest/activity/activities/?model_alias=deep_service/operation&id=196
				
			

The response:

				
					{
    "totalRecords": 7,
    "items": [
        {
            "entity_id": 124,
            "type": 1,
            "description": "<p>Dear user, I kindly ask you to give us a date to get your computer.<br />The technician is available tomorrow at 2 pm or the day after tomorrow at 3 pm.<br /><br />Thank you.</p>",
            "portal_visibility": 1,
            "frontend_visibility": 0,
            "started_at": null,
            "ended_at": null,
            "duration": null,
            "contract_id": 0,
            "contract_line_id": 0,
            "contract_line_qty": "0.0000",
            "created_by": "admin.demo",
            "model_alias": "deep_service/operation",
            "model_id": 90,
            "status": null,
            "formtemplate_id": 44,
            "disable_routing": 0,
            "updated_at": "2023-02-07 10:41:35",
            "created_at": "2023-02-07 10:41:35",
            "create_by_data": {
                "username": "admin.demo",
                "display_username": "DEMO ADMIN",
                "avatar_url": "https://kevin.deepser.net/media/user/image/default/12.png"
            },
            "created_at_date": "7/2/2023 10:41 AM"
        },
        {
            "entity_id": 125,
            "type": 1,
            "description": "<p>I prefer tomorrow at 2PM.</p>\r\n<p>Thank you.</p>",
            "portal_visibility": 1,
            "frontend_visibility": 0,
            "started_at": null,
            "ended_at": null,
            "duration": null,
            "contract_id": 0,
            "contract_line_id": 0,
            "contract_line_qty": "0.0000",
            "created_by": "user",
            "model_alias": "deep_service/operation",
            "model_id": 90,
            "status": null,
            "formtemplate_id": 44,
            "disable_routing": 0,
            "updated_at": "2023-02-07 10:43:14",
            "created_at": "2023-02-07 10:43:14",
            "create_by_data": {
                "username": "user",
                "display_username": "Demo User",
                "avatar_url": "https://kevin.deepser.net/media/user/image/default/9.png"
            },
            "created_at_date": "7/2/2023 10:43 AM"
        }
]
}

				
			

CMDB CI API

The CMDB CI entity is used to manage all CIs in Deepser (devices, softwares, contracts, etc.).
CIs can be created by Administrators, Agents and Key Users.
End Users cannot access this resource via API.

Endpoints

http://deepserhost/api/rest/cmdb/ci/[id]
http://deepserhost/api/rest/cmdb/cis

Roles

Here we list all the permissions by user role regarding the API:

 AdmininistratorAgentKey UserUser
Actions AllowedRETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE
DELETE
 

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

FieldMeaning
nameThe name of the CI. Usually a brief description.
type_idThe type of the CI. It is a very important value to manage the organization of the CMDB.
class_idThe Class the CI belongs to.
subtype_idThe Subtype of the CI. It is a very important value to manage the organization of the CMDB.
category1The category (1st Level) of the CI. It can be used according to the category of the Service module, in order to link Operations and CIs.
category2The category (2nd Level) of the CI. It can be used according to the category of the Service module, in order to link Operations and CIs.
category3The category (3rd Level) of the CI. It can be used according to the category of the Service module, in order to link Operations and CIs.
descriptionLarge description of the CI.
statusThe status of the CI. It is an important value to manage the lifecycle of the element.
priority_idPriority of the CI from the operator perspective.
urgency_idUrgency of the CI from the requester user perspective.
business_impact_idBusiness Impact of the CI from the organization perspective. If a CI is not available, the business impact represents the enormity of the situation and can be in terms of people, finances, systems, etc. For example, it can describe: the number of people affected by the CI outage or the potencial financial losses, or the number of other systems affected.
serial_numberThe serial number of the CI.
notesLarge Notes field.
front_imageThe main image of the CI.
back_imageThe back image of the CI. For example, if the CI is a rack, we can take a photo of the back side in order to see the connections or the cables.
assigned_company_idCompany that has taken in charge the CI. It is typically a Service Provider Company that has to monitor the CI. This field is very important to give the right visibility on the CIs. If a user has company restricted visibility, he cannot see CIs of other companies. Notice that a user with restricted company visibility can always see both CIs with its company in the Assigned Company OR Owner Company field.
assigned_group_idUser Group that has taken in charge the CI. It is typically a Service Provider Group of agents/key users that has to monitor the CI. This field can be left blank if there is no specific group assigned to the CI, otherwise it can be used to restrict permissions to groups.
assigned_usernameThe users who has taken in charge the CI. It is typically a Service Provider agent/key user that has to monitor the CI. This field can be left blank if there is no specific user assigned to the CI, otherwise it can be used to restrict permissions to single users.
owner_company_idCompany that is the owner of the CI. It is typically a Customer Company that uses the CI. This field is very important to give the right visibility on the CIs. If a user has company restricted visibility, he cannot see CIs of other companies. Notice that a user with restricted company visibility can always see both CIs with its company in the Assigned Company OR Owner Company field.
owner_group_idUser Group that owns the CI. It is typically a Customer or User Group of end users that can open requests on the CI. This field can be left blank if there is no specific group that owns the CI, otherwise it can be used to restrict permissions to groups (eg: when a user submits a request it could link only CIs owned by his user group).
owner_usernameUser that owns the CI. It is typically a Customer or end user who can open requests on the CI. This field can be left blank if there is no specific user that owns the CI, otherwise it can be used to restrict permissions to users (eg: when a user submits a request it could link only CIs owned by himself).
versionThe version of the CI. Deepser stores in its DataBase every version of the CIs. We can always know the changes, the user that made a change and the date.
created_atCreation date of the record.
updated_atDate of the last update on the system.
updated_byThe user that has lat updated the CI.

Deepser Fundamentals

This course will cover everything you should know to start doing advanced configuration in Deepser.
We will talk about UI, Grids, Forms and the two Possible portals.

Deepser Backend

The back-end screen of Deepser is organized into areas.

  • In the upper left area (1) there’s the User Menu.
  • In the left area (2) there’s the Navigation Menu, where we can find all the modules accessible from the back-end.
  • In the upper area (3) there’s the Global Search bar.
  • The textbox in that bar allows a full-text search on all the elements of the system. The rule is that the search is on the most important fields of every records: user name, title of an activity, name of the company, etc.
  • In the central area (4) there’s the Main Screen.

Note: the back-end is accessible only by Administrators, Agents and Key Users. End Users can only login to the User Portal.

Deepser User Menu

The User Menu of Deepser contains all the links to edit the user profile.

Below the icon with your avatar and name, clicking on the arrow, you can expand the menu:

The items of the menu are:

  • My Account: link to the page with all informations about the current logged in user, where he can modify his personal information: avatar, language, timezone, etc.
  • Portal: link to the End User Portal. A user that access the back-end can surf the User Portal by clicking this link.
  • Log Out: to disconnect from the system.
  • Help: link to the on-line help.

Deepser Navigation Menu

STRUCTURE

The Navigation Menu of Deepser contains the main links to the modules that compose the software.

Using this menu it is possible to access all the screens of the main functions of the software back-end portal.

The Navigation Menu has 2 main sections:

  • Menu items visibile to all users: they are the modules in which a user can manage Activities, Requests, CMDB, take a look at the Dashboard, etc.
  • System item: only a user with role Administrator can access this item.

The Navigation Menu is different from user to user, based on the user permissions:

  • Role: a user with role Administrator can access al the modules, even the configuration modules. A user “Agent” or “Key-User” cannot access the configuration module items (the menu System). A User (End User) cannot access to the back-end.
  • Module Visibility: a user with role Agent or Key-User can see only certain modules. This is possibile thanks to the ACL (Access Control Lists) configuration of Deepser.

The items in the Navigation Menu can contain sub-menus. In this case Deepser adds an icon on the lower corner of the menu item:

By clicking on the item with that icon we can expand the sub-menu, with other items, eventually expandable themselves:

If we select an item with no sub-menu the Main Screen of Deepser will be redirected to the main screen of the chosen module.

 HIDE NAVIGATION MENU

To make the use of the tool faster, it is possible to hide the Navigation Menu and to expand the main screen.

To hide the navigation menu click on the blue button near the global search textbox.

Global Search Usage

The Global Search Bar lets you easily find all records in the system: for example and Activity, a Support Request, a User, a Customer, a File Attachment, etc.

The Global Search textbox compares the text in it with the unique ID and the name of the entity and returns a list of all possible matches (if the record doesn’t have a Name field then another identification field is compared, for example a file name of an attachment or a title of an appointment).

Near the Global Search Bar, the blue button lets you hide the Navigation Menu, expanding the Main Screen.

Deepser Home Page

The Home Page of Deepser contains all the information regarding the module selected in the Navigation Menu.

By default, the first screen showed to a backend user after the login is the Dashboard, where you can see the graphs to easure the quality of your service real-time.

Note: The initial page of a backend user can be changed by system administrators.

To understand the details, the functions and the structure of the Home Page of Deepser, we will take a look at the Service Module.

Click on the item “Service” in the Navigation Menu on the left, we will see the sub-menus with all the Service Types in the system.

Note: the item “All” is always present and it is used to access all the Requests, without filtering the Service Types.

Selecting a menu item, the main screen of Deepser will show a grid with the requests (Operations) in the system and visibile based on the current user’s permissions.

Grids

GENERAL OVERVIEW

In Deepser data are displayed via grids.

Deepser’s grids are very flexible, however, thanks to the native features of customization, sorting, filter records in them.

Deepser allows you to manage entities values directly from the grids, without even opening the relative form, through the help of Mass Action preconfigured (or configurable).

Each grid can also be exported in *. xlsx or *. csv format in order to consult their data outside Deepser.

Filters and Order

FILTERS

In Deepser you can filter the records inside the grids according to the values of one or more fields displayed as columns.

The available filters are located immediately below the grid column header.

The way in which the filter is defined on the column values depends on the type of the field:

  • Text box
  • Date Range
  • Numerical range
  • Select-box with single selection
  • Multiple selection select-box

Once the filters have been set, to apply them to the grid, click on the Search button at the top right.

To remove the filters applied to the grid instead, click on the Reset filters button on the other right next to the Search button.

ORDERING

In Deepser you can sort records in grids by the value of any field (grid column).

To sort, simply click on the column header.

At the first click the direction of the order will be increasing, at the second click the records will follow a decreasing order.

Export Data

In Deepser all grids can be exported in *.xlsx or *.csv format.

This makes it possible to consult the data even outside the application.

The export keeps the filters and sorting applied to the grid at that time.

To export the grid you must first choose the format of the file that will be produced, by default XLSX will be proposed, from the select-box in the middle of the page, above the grid.

To download the export file, click on the download icon to the right of the chosen format.

At this point, before generating the file for download, the system will ask if you want to export only the visible records, or all the records from the other pages where the records have been divided.

Once you have decided which records should be exported, clicking one of the two modal’s buttons will start downloading the file.

Mass Action

USING MASS ACTION

In Deepser it is possible to operate on the entities visualized in a grid directly from the grid itself, through some massive actions preconfigured.

To use this feature you need to check, through the check-box in the leftmost column of the grid, the record(s) on which you want to perform the action, or use the short cut(s) of quick selection/de-selection.

 

Once the records have been selected, from the Actions select-box at the top right, select the action to perform.

Clicking the Submit button, to the right of the Actions select-box, will execute the selected mass action on the ticked records.

 

EXAMPLE: PRIORITY CHANGE

In the following example we will use the mass action Modify Priority on some service operations in grid

Step 1. Record selection

 

Step 2. Mass action selection

 

Step 3. Selecting the new value Priority

 

Step 4. Performing mass-action

 

As you can see the values of the selected records have been changed by the mass action.

 

Mass Action Configuration

In Deepser it is possible to define, through custom code, actions to be executed on the records of a grid in a massive way.

To define mass actions, from the grid configuration menu check the check-box to enable mass-actions and click on the icon </> to display the scripting area.

EXAMPLE 1 – MASS ACTION WITH SELECT

In this example we want to configure a Mass Action, in CMDB module grid, to massively change CIs’ Status.

				
					// retrieve all states from the list cmdb_ci_status as associative arrays
$statusArray = Deep::helper('deep_list')->loadListValues('cmdb_ci_status')->toOptionHash();
// initialize html component
$this->addMassActionItem('status', [
    'label'      => Deep::helper('deep_cmdb')->__('Stato'),
    'additional' => array(
        'status' => array(
            'name'   => 'status',
            'type'   => 'select',
            'class'  => 'required-entry',
            'label'  => Deep::helper('deep_cmdb')->__('Status'),
            'disable_js_select' => true,
            'values' => $statusArray,
        )
    ),
    //callback is the method that contains the logic of the action
    'callback' => function() {
        /** @var Deep_Grid_Model_Grid_Massaction_Callback $this */
        /** @var Mage_Core_Model_Resource_Db_Collection_Abstract $collection */
        $collection = $this->getGrid()->getModelInstance()->getCollection();
        //$this->getIds() returns the id of the selected cis
        $collection->addFieldToFilter('entity_id', ['in' => $this->getIds()]);
        // $collection contains the instances of the selected cis and we iterate on them
        foreach($collection as $ci){
            //$this->getValue() contains the id of the new status, the selected one
            //set the new ci status
            $ci->setStatus($this->getValue());
            //save the ci
            $ci->save();
        }
    }
]);
				
			

EXAMPLE 2 – MASS-ACTION WITH DATE-PICKER

 In this example we want to configure a Mass Action, on a grid in Operation module, to massively set the Date Expiration of service operations.

				
					//retrieve the icon that will open the date-picker
$img = Deep::getDesign()->getSkinUrl('images/grid-cal.gif');
$this->addMassActionItem('due_date', [
    'label'      => Deep::helper('deep_service')->__('Due Date'),
    'additional' => array(
        'due_date' => array(
            'name'   => 'due_date',
            'type'   => 'date',
            // define the date format
            'format'   => 'yyyy-M-d',
            'image' => $img,
            'gmtoffset' => true,
            'label'  => Deep::helper('deep_service')->__(''),
            'disable_js_select' => true,
            'build_on_load' => true,
        )
    ),
    //callback is the method that contains the logic of the action
    'callback' => function() {
        $collection = $this->getGrid()->getModelInstance()->getCollection();
        //$this->getIds() returns the id of the selected operations
        $collection->addFieldToFilter('entity_id', ['in' => $this->getIds()]);
        // $collection contains the instances of the selected operations and we iterate on them
        foreach($collection as $operation){
            //$this->getValue() contains the new date that has to be set
            //set the new due date
            $operation->setDueDate($this->getValue());
            //save the operation
            $operation->save();
        }
    }
]);
				
			

Grid Creation and Cloning

In Deepser you can create new grids, and configure them appropriately, in order to respond immediately to the needs of the agents who will work on it.

CREATING A GRID

To create a new grid, starting from zero, we have to follow only two simple steps:

Step 1

Click the New icon, circled in the figure, in the lower left area of the grid menu.

Otherwise you can also create a new grid by clicking on the icon circled in the following screeshot, next to the badge containing the name of the current grid, to display the menu.

Then click on New Grid

Step 2

The system will now ask you to enter a name for the new grid.

Once you have entered the name, click the Save button.

At this point the new grid will be created and can be selected from the grid menu.

As we can see from the following screenshot a new grid has no exposed columns (visible columns) and therefore appears “empty”. In this case it will be necessary to configure them manually.

CLONING A GRID

The grid cloning function allows you to create new grids by cloning the configuration of an existing grid.

Step1

Once positioned on the grid you want to clone, click the Clone icon, circled in the figure, at the bottom right of the grid menu.

Otherwise you can also clone a grid by clicking on the circled icon in the screenshot below to display the menu.

Then click on Clone Grid

Step 2

The system will now ask in which section of the current module should be saved.

Once selected from the select section, click the Save button.

Note: — is the option that indicates the All section.

At this point the new grid will be created and can be selected from the grid menu.

As we can see from the following screenshot the clone grid is composed by the name of the “original” grid with the addition of the prefix NEW- .

The new grid will have the same exposed columns (visible columns) as the original one, all other possible configurations will be copied as well.

Deleting  a Grid

To Delete a grid, go to the desired grid and click on it (1) and afterwards click on the edit icon(2)

Once the grid editing menu is open, click on the “Delete” button located in the bottom right corner of the window.

Configuring Grids

In Deepser you can configure grids to meet the needs of the Agents, with the aim of facilitating operations as much as possible by creating a useful and immediate interface.

To access the configuration menu of a grid, once positioned on the grid you want to modify, click the pencil icon next to the badge with the name of the current grid.

VISIBLE COLUMNS MANAGEMENT

To make a column visible in a grid, simply drag and drop it from the available columns (on the left) to the visible columns (on the right).

To remove a column from the grid simply do the opposite operation, i.e. drag&drop it from the visible columns (on the right) to the available columns (on the left).

COLUMN CONFIGURATION

To change the configuration of a single column, once selected among the visible columns (by clicking on it) its configuration menu will appear.

HEADER

Through this field you can change the column header as it is displayed in the grid.

TYPE

Indicates the type of data showed in the column.

It is related to the type of field element that the column displays. (For further information see the lesson related to custom fields)

FILTER

Checking this option makes a column filterable.

MULTI-FILTER

By checking this option you can define multiple values in the column filter.

This option only affects Select and Option types

SORTABLE

By checking this option the grid can be sorted according to the column values.

OTHER CONFIGURATIONS

In the area to the right of the grid configuration menu there is a section containing other configuration tools

GRID NAME

In this field we can specify the name of the grid.

PREPARED COLLECTION

Using the Query Builder it is possible to define filters on the data while it is being retrieved from the database, which cannot be removed using the Filter Reset button. E.g.: you want to create a grid containing service operation not in Closed state.

MASS ACTION

Through the check-box you can define whether mass-actions should be enabled in the grid.

ENABLE EXPORT

Through the check-box it is possible to define the grid to be exported or not.

GROUPS VISIBILITY

List of groups for which to make the grid visible.

Note: Super Admin users will see all grids.

Advanced Collection Configuration

In Deepser you can define, through custom code, filters on the collection of data shown in the grid.

This feature is useful when you want to define advanced conditions that cannot be expressed by query builder.

To define custom conditions on the collection, from the grid configuration menu click on the icon </> to view the scripting area.

 

Inside it you can insert the PHP code to handle on the data collection through the related query.

EXAMPLE

In this example you want to configure a custom filter on the Collection of service operations recovered from the database.

Through this filter only the service operations assigned to the groups of which the user is a member will be retrieved.

				
					// Deep::helper('deep_admin')->getCurrentUser() returns the current user object instance
// getGroupIds() returns entity_ids of of the groups of which the current user is a member
$currentUserGroups = Deep::helper('deep_admin')->getCurrentUser()->getGroupIds();
// modify the where clause of the query by adding our condition
$this->getCollection()->getSelect()->where("main_table.assigned_group_id IN (" . implode($currentUserGroups,',')
				
			

Grids Render and Options Configuration

In Deepser you can define, through PHP code, Renderer custom for each column of the grid, and the domain of the possible Options type columns.

To configure these two components, from the configuration of a grid, after selecting the column to modify, just click on the icon </> to display the two scripting areas, within which you can enter your code.

Grids Custom Options Configurations

In this example we want to define the domain of the possible options of an Options column.

A typical case in which you want to define “manually” the options of a column is the one in which a field, is the Device field of service operations.

In fact, this custom field appears as select in the form and allows you to associate a ticket to a ticket from the Devices class.

When this field is displayed in grid, the CI entity_id will be displayed and not its name.

In order to display its name in grid and use a select filter, it is necessary to properly configure the column.

To achieve this it is necessary to access the grid configuration page and set the column type to ‘Options’ and then insert some PHP code in the ‘Options’ scripting area.

Insert the following code inside the scripting area:

				
					//retreive of the CI collection
$ciCollection = Deep::getResourceModel('deep_cmdb/ci_collection');
//filter in the Clause where of the query to retrieve only Devices class ICs
$ciCollection->addFieldToFilter('class_id',['eq'=>2]);
//convert the collection into an associative array
//the keys is the CI Id and the value the CI Name
$optionsArray = $ciCollection->toOptionHash();
return $optionsArray;
				
			

Now the Device column will display the Name of the related CI.

In addition, grid records can be filtered via select or multiselect

Grids Renderer Tooltip Example

In this example we want to configure the custom rendering of the Title column in a grid of the Service module to display the description of the ticket, when the mouse passes over.

The code you have to insert PHP codethat return a string containing the HTML code that has to be rendered in the grid cell.

We will then use PHP to access the operation fields and to properly build the string containing the HTML code.

To enter the custom renderer configuration code click on the </> icon in the Renderer field to display the scripting area.

And insert the following code:

				
					//print the ticket title
$html = '<div title="_" class="deepTooltip" data-tooltip-content="#deep_tooltip_content_'.$row->getId().'" style="min-width:300px;font-weight:bold;">' . $value . '</div>';
//define tooltip content ticket Description
$html .= '<div style="display:none;"><div id="deep_tooltip_content_'.$row->getId().'">'.$row->getDescription().'</div></div>';
//initialise tooltip js component
$initToolTip = Deep::registry('deep_grid_title_tooltip');
if(!$initToolTip){
    Deep::register('deep_grid_title_tooltip', true);
    $html .= '<script type="text/javascript">
        jQuery(document).ready(function(){
            jQuery(".deepTooltip").tooltipster({
                theme: "tooltipster-shadow",
                interactive: true,
                side: "right"
            });
            jQuery(".deepTooltip").attr("name", "");
        });
    </script>';
}
 
return $html;
				
			

Now, passing with the mouse pointer over the Title column, a tooltip containing the description of the Operation in that row will appear.

Grids Renderer Link Example

In this example we want to configure the Title column, in a grid of the Service module, to contain a link to open the operation in another tab.

To configure this behavior we must insert in the Renderer scripting area of the Title column the following code:

				
					//retrieve the title of the operation
$value = $this->escapeHtml($row->getTitle());
//I define the url to insert in the link
$url = Deep::getUrl("*/service_operation/edit", ["id" => $row->getId()]);
//the string with the html code is returned to generate the link
return "<div style='width: 300px; font-weight: bold'><a href='$url' target='_blank'>$value</a></div>";
				
			

Grids System Configuration

GRID RELOAD INTERVAL

In Deepser there is a system configuration that allows you to define the reload interval of the grids.

You can change the value of this configuration from the System>Configuration>Grids>Configurations section the value is expressed in seconds.

The recommended default value is 300.

Form Template Theory

All Deepser entities have a template form by default.
In particular, this Form Template is the one that is applied if there are no other templates for that entity in the system.

The moment a record is saved to the system with a certain Form Template, it is storicized in the DataBase and is no longer automatically modified by the system. At this point you can only change the Form Template manually.
This behavior, which is the basis of Deepser, is used to provide certainty about the Form Template used and establishes that once you have collected a set of information and saved it in the database, it will be displayed in the same layout as the one used to create the record. Obviously, as we said, there is always the flexibility to modify the layout manually.

The Form Template, instead, varies dynamically when the record is not yet saved in the DataBase.
This behavior allows you to adapt the form fields (and the layout of the record entry screen) according to the characteristics of the data you are entering into the system.
As said before, if you need certain information for a category or for a type of Service Operations, you can configure as many Form Templates as there are layouts that you want to set.

The dynamic modification of the Form is made possible thanks to a set of rules (Form Template Rules) that are inserted during the configuration phase of the Template.
The Form Template Rules in fact play a fundamental role in the configuration of the dynamic change of the templates and must be implemented with great care to create a flexible and powerful system of dynamic forms that adapt themselves according to the data we are inserting in the system.

FormTemplates

All Deepser editing forms are customizable through a graphical configuration editor, you can also apply specific templates to records according to their characteristics.

The goal is to provide Agents and Users with a template containing a minimum set of data, in order to speed up, as much as possible, the opening and handling of requests.

As you can see from the following images the Form Templates can be different in shape and number of fields, to meet specific needs.

FormTemplates Structure and Buttons

FORM STRUCTURE

In Deepser forms are composed of the following components:

  • Tab
  • Fieldset
  • Fields
  • Buttons

TAB

By using tabs you can organize the fields of a form into several different “screens”.

You can navigate between them in the menu on the left (indicated by the green box in the figure).

It is useful to use tabs when the form contains many fields, and would become too long vertically, then you can divide and organize them into different tabs according to their context.

FIELDSET

Fieldsets (set of fields) are the “containers” of the fields of a form.

A single tab can contain multiple fieldsets.

Fieldsets are useful to group fields according to their context; for example it is useful to group the general information of a ticket, or the data concerning the applicant of a ticket, or the system fields concerning the creation and/or the last modification of a ticket.

FIELDS

The fields are simply the fields of an entity (Service Operation, CMDB CI, CRM Contacts etc.) such as Title, Name, Description etc.

The fields of a form are organized in fieldsets.

Some fields may not be editable or may be pre-filled, depending on the configuration made by system administrators.

BUTTONS

The buttons on the forms in Deepser allow you to perform actions that system administrators have decided to make available.

The standard buttons mainly used are the following:

BUTTONSIGNIFIED
ApplySave and submit the current form, but stay on the same page.
SaveSave and submit the current form, but return to the previous page. Example: a Service Operation is saved, and returns to the main grid.
DeletePhysical deletion of an entity, which will be permanently deleted from Deepser.
ResetRoll-Back of changes made to form fields but not yet saved. The entity will be restored with the data updated to the last time the enitity was saved.
BackReturn to the previous page.

Form Template Selection and Creation

TEMPLATE SELECTION

In Deepser for each entity you can have different form-templates.

To manually select a template (as a user with Role Administrator or Agent) just open the Template menu and select it.

TEMPLATE CREATION

To create a new Form Template, from the Form Template menu inside a record (as user with Role Administrator or Agent) you can select the New Form Template item.

At this point Deepser will ask you to specify a name for the new Template.

Once you have entered the name click on the Save button to create the Template.

The new template will be a clone of the template that was “loaded” at the time of creation.

Once saved, the Template will be selectable from the form-template menu.

Form Template Configuration

In Deepser you can change the structure of a form-template quickly, through a simple and intuitive graphical interface.

To access the configuration interface of a form-template click on the “pencil” icon (visible only by users with Role Administrator or Agent) in the upper left area of each Form Template.

EDIT FORMTEMPLATE

The configuration interface contains the configuration data of the Form Template, and the components that define its structure displayed in a tree.

From here you can change the name of the template after its creation.

EDIT RULES

By clicking on the ‘Edit Rules‘ tab you can assign a priority to a template and define the loading rules.

Priorities and Rules define the template to be loaded dynamically when creating a new record. The priority defines the order in which the templates will be tested, in sequence, until one is found whose condition, expressed through the rules, is verified.

In the following example the template is assigned a priority of 150 and the query builder expresses the rule: this template should only be loaded if the Category1 field is ‘Network‘.

Form Template Structure Configuration

Form Templates in Deepser are structured according to a hierarchy of container elements.

On the first level there is the Form, which can contain a set of Tabs, which in turn can contain Fieldsets. Each Fieldset contains a variable number of Fields.

To add new items within the Form Template configuration screen, right-click and add the chosen “sub-element”.

FILDSET AND TAB

When adding new tabs or fieldsets, their position can be simply changed by drag&drop.

Once you have created a Tab or Filedset you can change its name from its configuration screen.

Formtemplates Fieldset Configuration

To access the configuration screen of a fieldset simply select it in the tree structure in the Form Template configuration screen.

You can define the name of the Fieldset and the status.

Inside the Fieldset there are the fields visible inside the Form.

On the right side there are all the available fields, in the center those visible inside the selected Fieldset.

You can show a field in a Fieldset by simply drag and drop it from the Available Fields to the Fieldset.

To delete a field from a Fieldset simply drag&drop it from the Fieldset to the Available Fields area on the right. At that point, the Field will be available to be inserted in other Fieldsets.

Note: fields cannot be replicated on the various Fieldsets, so if the field is inserted in a specific Fieldset it cannot be replicated also in another Fieldset (for example) in another Tab.

Formtemplates Buttons Configuration

From the Form Template component tree you can also manage the buttons.

By right-clicking on a button you can delete it.

Simply selecting it, instead, you can act on its configuration.

The fields have the following meaning

FIELDSIGNIFIED
LabelText in the button.
CodeAdditional identification. Used for system buttons only.
AreaForm Area where the button has to be displayed (Header or Footer).
StatusIf Disabled the button will not be added to the form.
ClassWith this field you can assign one or more css classes to the button.
OnClickScripting area where you can define the OnClick action of the button.

Formtemplates Field Configuration

Form fields are editable within Fieldsets.

To change the appearance and configuration of the individual Field, click on the “gear” icon in the Field.

The Field management popup appears at this point:

The configuration fields of the Field have the following meaning:

FIELD DESCRIPTION
Default Value Default value of the field. This value is defined at the Form Template level. Note: For Select type fields you must specify the key of the option to pre-select it.
Disabled Indicates whether the field is active or not. A disabled field will not be part of the form submitted for saving.
Readonly Indicates whether the field is read-only
Required Indicates if the field is mandatory. If mandatory, the form cannot be saved until the field has a value.
Reload Form This field is important for the application of the Form Template Rules. If it is set to “Yes“, it means that when you edit the field, the form is reloaded and any Form Template Rules are applied.
Columns Indicates the size of the field. The field can have a maximum size of 6 and minimum size of 1. A field that occupies 6 columns, graphically speaking, will occupy the entire line of the form.
Margin Left Indicates the left margin of the field. Note: The sum of the value set in the Columns field and the left margin will always be less than or equal to 6
Line break Indicates if other fields can be rendered on the same line.
Hidden Indicates if the field is hidden.
Readonly for groups By this field, you can define the field will be seen as Readonly form members of some groups.
View only by groups By this field, you can define the field will be seen only by the members of some groups.

Advanced Form Template Rules

In Deepser you can define the rules for loading Form Templates via PHP script.

It is useful to be able to define conditions “manually” by scripts when they are too complex or particular to be expressed by query-builder.

To define a rule by scripting, go to the configuration menu of the Form Template, move to the tab (on top) Edit Rules and click the icon </> above the query-builder  (as shown in the picture).

In this area you will find the code automatically generated by query-builder that you can integrate or replace with custom PHP code.

EXAMPLE: TEMPLATE FOR IT SECOND LEVEL MEMBERS

In the following example we want to make a template visible only to users who are members of a specific group: IT Second Level.

To do this you need to enter the following PHP code in the Rules scripting area.

				
					//retrieve the current user
$currentUser = Deep::helper('deep_admin')->getCurrentUser();
//IT Second Level group id = 5
//check if the user is in IT Second Level group
if($currentUser->isInGroup(5)){
    //original condition generated by the query-bulder
    if( $this->getModel()->getData('type_id')==1 &&
            ( $this->getModel()->getData('category1')==5 ||
                $this->getModel()->getData('category1')==17 ||
                $this->getModel()->getData('category1')==2 )){
        //if both conditions are verified the template form is loaded
        return true;
    }
}
else{
    //else return false and evaluate the rules of the next template
    return false;
}
				
			

Custom Button Configuration

You can define, within a Form Template, several custom buttons to perform custom actions.

DEFINITION OF CUSTOM ONCLICK ACTIONS

To access the script area to define OnClick custom, from the configuration screen of a button, click on the icon </> next to the OnClick label

At this point you will open the scripting area, where through PHP code, you can build the string containing the JavaScript code that will implement the action desiserata.

EXAMPLE 1: SEARCHING FOR THE TITLE OF AN OPERATION ON GOOGLE

In the following example we want to implement an OnClick action that searches on google the title of an operation and displays the search results in a new tab.

				
					#retrieve from the current site (ticket) its title
$operationTitle = Deep::registry('current_model_instance')->getTitle();
#build the url to search on google
$url = "http://www.google.com/search?q=".urlencode($operationTitle);
#return the onlclick code of the HTML element
return "window.open('$url')";
				
			

EXAMPLE 2: CLOSING AN OPERATION AND SENDING REPORTS

In the following example we want to implement an OnClick action that puts an operation in a closed state, and gives the user the possibility to send the report to the applicant, through the email event already configured.

				
					// confirmation prompt message
$msg = $this->__("Sent report?");
// $js is a string that contains JavaScript code
$js = <<<JS
//status field is set to Closed
jQuery('#operation_status').val(3);
//confirmation prompt element configuration
jQuery.confirm({
    title: null,
    content: '{$msg}',
    containerFluid: true,
    closeIcon: true,
    buttons: {
        save: {
            text: 'OK',
            btnClass: 'btn-blue',
            action: function(){
                //if user press OK trigger the send report email event
                jQuery('#operation_cust_sendreport').val(1);
                //save current operation
                saveAndContinueEdit();
                return true;
            }
        },
        cancel: {
            text: 'NO',
            action: function () {
                saveAndContinueEdit();
                return true;
            }
        }
    },
});
//end of JavaScript string
JS;
//return JavaScript code
return $js;
				
			

Buttons Conditional Hiding

It is common to show a button only when certain conditions are verified.

To do this you need to assign a CSS class (the name it’s your own choice) to the button.

The CSS class will provide an easy way to select via jQuery the button and then disable it.

The code to hide a button must be executed when the formi s loaded, so we must use the Script area in the Form Template configuration menù.

EXAMPLE 1: HIDE OPERATION BUTTON IF IT IS ALREADY IN THE CLOSED STATE

In the following example you want to hide the Close Operation and Send Report button (Example 2 section OnClick Custom) if the ticket is already in a closed state.

Step 1: We assign a CSS class to the button from the button configuration screen.

Step 2: Go to the Form Template configuration screen, expand the Scripting Script area by clicking on the </> icon.

And insert the following code:

				
					// $js is a string that contains JavaScript code
$js = "";
// if status is closed
if (Deep::registry('current_model_instance')->getStatus() == 3)
    //add to JavaScript string the jQuery code tu hide the button
    //note the css class defined in step1 is used in selection
    $js .= "jQuery('.btn-close').hide();";
//return JavaScript code
return $js;
				
			

User Portal

The Deepser user portal, is the frontend interface presented to end users, and if properly configured, it allows to easily create and consult tickets, get access to CMDB, CRM, Knowledge base and password manager.

The user portal is displayed after logging in into the deepser frontend.

Note: The domain select above the ‘User Name’ field is used to choose which domain controller to use to log in, if configured.

If the login was successful, the User Portal will show.a

Browsing the user portal

The Deepser user portal is made out several areas, the most important section of the page is functional to the creation and management of tickets, while the drop-down menu allows you to access the other features.

The meaning of the various sections is here described

FunctionSectionDescription
Help Desk(Ticketing)Service GroupIndicates the group to which a certain type of service belongs. For example, requesting a new device is part of the IT Support group.
Service RequestService RequestIndicates the type of ticket that will be created. For example, the request for a new device is part of the ‘Requests’ type.
Service OperationsService OperationsShows All tickets that are configured to be visible to the current user. There may be multiple grids to make it easier to view, for istance , the grid displaying  open tickets, the grid displaying tickets being processed and the grid displaying closed tickets.
CMDB, Knowledge Base, Password ManagerDropdownAppears by clicking on the arrow to the right of the user, allows you to navigate through the other modules configured as visible in the user portal.

Managing Tickets in The User Portal

The first function of the user portal is to allow Deepser end users to create and manage tickets.

1 – First of all login with your credentials to the user portal through the login screen

2 -Then select the interested group, and the type of ticket you want to create (in the example you want to create a request from the IT Support group).

3 – At this point, the ticket creation form will open, this must be be filled in with the interested values (in the example we ask for a new laptop), once filled in click on Apply.

3a – The meaning of the fields is as follows

FieldDescription
CategoryThe category and the consequent subcategories of the ticket.
TitleThe title of the Ticket
UrgencyThe urgency is the ticket
Knowledge BaseField dynamically populated with all the articles that match the ticket title in terms of tags.
DescriptionTicket description

4 – By default, the created ticket will appear under the Open Requests grid, clicking on it you can see the details.

5 – Once opened, you can follow updates on ticket resolution, add attachments, comments, etc.

User Portal Additional Features

In addition to ticket management, the user portal also allows access to the CMDB, CRM, Knowledge Base and Password Manager, all through the drop-down menu, which can be activated by clicking on the arrow to the right of the current user.

This is the complete menu of all the items related to the various modules configured in Deepser.

ItemDescription
CMDBContains all visible entries in the Configuration Management Database module.
CRMIt contains all the contacts, companies and visible opportunities of the Customer Relationship Management module.
Knowledge baseIt contains all the support articles, internal guides, etc. of the Knowledge base.
PasswordIt contains all visible passwords of the password manager module.

Note: Each functionality is simply introduced, to have a detailed guide, refer to the respective articles of the Academy.

Configuring Portal Groups

SERVICE OPERATION CONFIGURATION OVERVIEW

In order to correctly display help desk services on the portal, the Portal Groups, Portal Request and Portal Operations must be configured correctly.

The following guide aims to create a new service Group Training, in which it will be possible to make training requests, and then make it visible in a customized grid.

The meaning of the areas is the following:

SectionDescription
Service GroupIndicates the group to which a certain type of service belongs in the portal. For example, requesting a new device is part of the IT Support group.
Service RequestIndicates the type of ticket that will be created. For example, the request for a new device is part of the ‘Requests’ type.
Service OperationsShow All tickets that are configured to be visible to the current user. There may be multiple grids to simplify the view, for example, the grid for open tickets, the grid for tickets being processed and the grid for closed tickets.

1 – Access to the item ‘Portal Group’ from the Backend of Deepser, through Sistem ->Portal->Group

2 – Add anew group on the portal by clicking the Add a portal Group button.

3 – Enter a name, the position where it will appear among the portal groups, visibility in the portal and status, as active. Finally save the new group.

Note: Portal Requests does not show any value because portal requests still must be configured. Moreover, if not visible, the field Portal Visibility, must be dragged inside the template form through the pencil-shaped edit button on the top left (to learn more about the topic visit the appropriate section of the academy).

Configuring Portal Requests

1 – To configure a new request, and make it part of a group, go to System->Portal->Request.

2 – Add a new request on the portal by clicking the Add portal Request button.

3 – Fill in the Request creation form, and then click on Save.

The meaning of the fields is as follows

FieldDescription
NameRepresents the name of the Portal Request.
TypeIt indicates the service type of the ticket that will be generated by this portal Request.
TemplateIndicates the Form template used when creating the request. It is advisable to create two templates, one for the creation, and a NO EDIT one to view the tickets created (for more information visit the dedicated section of the academy).
IconAllows you to choose an icon to be displayed in the portal next to the request.
Portal GroupsIndicates the group to which this Portal Request will belong.
DescriptionIndicates the description that will be shown under the request, this is useful to make clear to end users the purpose of this portal request.
UrlIt allows to transform the portal request to a link. So, if set, when you click on the request in the portal, it will not open a ticket, but the link.
StatusIndicates the status of the request portal(Enabled/Disabled )
Frontend VisibilityIf set to yes, it will make the request visible in the Guest Portal.

3a – After saving, the request will appear as visible within the group.

3b – In addition, the request will also be visible in the Users portal.

Configuring Service Operations in the User Portal

Deepser user portal allows immediate access to the tickets of which you have visibility, through the Service Operation grids, present in the lower part of the portal.

By default, there are 3 grids, Open Tickets, Loaded Tickets and Closed Tickets, and they show the tickets that the current user is requesting.

These grids are totally customizable, so they can show a collection of tickets, filtered according to the rules set.

This guide will show you how to create a custom ‘Ticket with High Urgency’ grid.

1 – Open the portal grid configuration, through System->Portal->Operation.

2 – This menu allows you to view and modify the grids in the user portal. Click on New to add a new grid.

3 – Enter a name, then click on Save.

4 – Enter the grid editing mode by clicking on the pencil button.

5 – Configure the grid to show the needed fields, with the required filters of the query builder, and selecting the groups that will have visibility (in this example a grid has been configured that displays all urgent tickets in open state). Finally click on Save.

Note: For more information on how grid editing works, see the appropriate section of the Academy.

6 – After following all the steps, a new grid will appear in the user portal showing tickets that meet the conditions set.

Enabling Other Modules in the User Portal

Through the user portal, it is possible to give end users access to CMDB, CRM, Knowledge Base and Password Manager modules. To make this possible, you need to Enable them

0 – First go to Deepser System configuration, going to System->Configuration->Portal->Configuration.

From here you can set the visibility of each module in the portal

ENABLING THE PASSWORD MANAGER IN THE USER PORTAL.

To enable the password manager, select Password, set Enabled to Yes, select the list of groups that will have access to the module in the user portal, and finally click Save Configuration.

ENABLE THE KNOWLEDGE BASE IN THE USER PORTAL.

To enable the password manager, select the Knowledge Base item, set Enabled to Yes, select the list of groups that will have access to the module in the user portal, and finally click Save Configuration.

Note: To be actually visible on the portal, both articles (accessible from the KB edit) and sections (System->Knowledge Base) must have Portal Visibility set to Yes.

For a detailed guide, please refer to the Academy’s topic.

ENABLE THE CRM MODULE IN THE USER PORTAL.

To enable the password manager, select the CRM item, for each type of item, set Enabled to Yes and select the list of groups that will have access to the module in the user portal, finally click on Save Configuration.

ENABLE THE CMDB MODULE IN THE USER PORTAL.

To enable the CMDB, select the CMDB item, set Enabled to Yes, the Enable Priority parameter allows you to decide whether to follow the value of the CMDB Portal Visibility item set for each user, or to enable it for all users, and finally click on Save Configuration.

ENABLE WORKLOGS IN THE USER PORTAL.

To show the activities to end users in the user portal, select the Activity item, set Show Worklogs to Yes, to allow end users to add and edit them, set Add/Edit Worklogs to Yes, and finally click Save Configuration.

Enabling Other Modules in the User Portal Grid

The CMDB, CRM and Password Manager modules, have editable grids in the user portal, this allows you to filter the display of each element, or organize them differently.

The following guide gives a brief view about the topic of editing grids, to learn more, go to the specific section of the Academy.

CHANGE THE PASSWORD MANAGER GRIDS IN THE USER PORTAL.

To change the password manager grid in the user portal, navigate to System->Portal->Password .

It will then open the grid displayed by default in the Users portal, to modify it click on the pencil icon, instead to create a new one, click on the new button.

MODIFY THE CRM GRIDS IN THE USER PORTAL.

To modify the CRM grid in the user portal, navigate to System->Portal->CRM, and select the type of element concerned (Account, Contact or Opportunity), the procedure applies to all three.

It will then open the grid displayed by default in the Users portal, to modify it click on the pencil icon, instead to create a new one, click on the new button.

MODIFY THE CMDB GRIDS IN THE USER PORTAL.

To modify the CMDB grid in the user portal, navigate to System->Portal->CI , and select the type of element concerned (Account, Contact or Opportunity), the procedure applies to all three.

It will then open the grid displayed by default in the Users portal, to modify it click on the pencil icon, instead to create a new one, click on the new button.

Guest Portal

The Guest Portal also allows users not registered in Deepser to access the system and take advantage of certain features such as opening Tickets or looking into the Knowledge Base.

In order to allow non-authenticated users to use these resources, they must be properly configured.

Enabling the Guest Portal

The guest portal is not enabled by default, to enable it go to the System > Configuration > Web > Default Pages section, enable the Enable Frontend option , and click on the Save Config button .

At this point the Guest Portal that will be loaded is the one already present in Deepser with its default configuration.

From the Guest Portal it will then be possible to return to the area dedicated to authenticated users by selecting the Login item from the menu (top right) .

Note: Once the Guest Portal is enabled, the new Home Page will be the latter, no longer the login screen.

LOGO MODIFICATION

The guest portal is fully configurable, by default neither ticket creation nor access to knowledge base articles is enabled.

To replace the Deepser logo in the Guest Portal home, go to System > Configuration > Design > HTML Head and load the new logo under Frontend Logo.

Guest Portal Visibility Configuration Overview

VISIBILITY CONFIGURATION OVERVIEW

On the Homepage, once enabled, the Guest Portal is present. In order to allow, through the latter, the opening of new Tickets, it is necessary to properly configure the Service components, and then enable them to be used in the Guest Portal: Service Types, Portal Group and Portal Request.

Enabling Service Types on the Guest Portal

To enable the creation of Service Operations from the Guest Portal, at least one Service Type must be enabled in the Guest Portal. Only Operations of the enabled types can be created.

1 – To enable a type go to the System > Service Configuration > Typologies section and after clicking on the desired type set the Frontend Visibility field to ‘YES’.

1b – If the Frontend Visibility field is not present, it must be added to the form.

To do this, enter the edit mode of the form by clicking on the pencil icon in the top left corner

1c – Finally, select the Form Type, via drag&drop, drag the Frontend Visibility field into the form and press Save, then refresh the page.

Adding a Portal Group in the Guest Portal

To enable the creation of Service Operations from the Guest Portal, it is necessary to enable at least one Portal Group to be visible in the Guest Portal.

To enable a Portal Group go to the System > Portal > Group section and after having clicked on the desired group set the Frontend Visibility field to ‘YES’.

Please Note: If the Frontend Visibility field is not present, it is necessary to add it to the form. To do this, enter the form editing mode (clicking on the pencil icon in the top left corner) and, using drag&drop, drag it into the form, then refresh the page so that the field is displayed.

Note: a Portal Group will be displayed in the Guest Portal only if it contains at least one Portal Request configured as visible (in the Guest Portal) and this is of a type configured as enabled (for the Guest Portal).

Adding a Portal Request in the Guest Portal

As for the portal dedicated to Endusers, Service Operations (Tickets) are created by Guest users through the configured Portal Requests.

1 – To enable a Portal Request go to the System > Portal > Request section and after clicking on the desired request set the Frontend Visibility field to ‘YES’.

Please Note: If the Frontend Visibility field is not present you need to add it to the form. To do this, enter the form edit mode (by clicking on the pencil icon in the top left corner) and, using drag&drop, drag it into the form, then refresh the page so that the field is displayed.

2 – If the Template field is valorized, remove the value by pressing the ‘x’ to the right.

Please Note: At this point, the loading of the formtemplate will respect the rules

3 – Now the user portal will show the requests of the configured type and group.

Editing Form Templates in the Guest Portal

Once the requests are made visible in the guest portal, they will have all the ticket fields filled in, which makes it necessary to edit the form template.

1 – Access the guest portal through an Admin user, to do this you need to remove all the right side of the url. (E.g. test.deepser.com/admin/system_account will become test.deepser.com)

 

2 – Select a request

3 – All fields can be set by default by the guest user, to modify the available fields, open the form editor.

4 – Once you have selected the correct fieldset, modify it as needed, keeping in mind that this form will be accessible to guest users.

Note: When a guest user opens a ticket, they will be recognizable by their email, so in this case the Requester Email field should be added as mandatory.

Enabling Categories in the Guest Portal

To make a Category visible in the Guest Portal you need to go to the System > Categories section of the Deepser backend.

1 – Once the desired category has been selected in the “Category” tab, set the Frontend VIsbility field to “YES”.

2 – If ad-hoc rules are defined for some models move to the “Models Visibility” tab and change within the rules the value of the Frontend VIsbility field.

Enabling Notifications for Guest Users

An Email Event ” REQUESTER USER – Operation Opened by Frontend User ” has been set up in Deepser to notify the “guest” user that the ticket has been created.

1 – By default the event is disabled, to enable it go to the System à Tools à Email à Event section .

2 – The related email template is configured to send via email the link that allows you to consult the ticket even to an unregistered user.

In Deepser it is possible to create custom email events, if necessary it will therefore be possible to define new events such as the notification of inserting a comment or the closing of the ticket.

Knowledge Base in the Guest Portal

The Guest Portal includes a section containing Knowledge Bases that have been configured to be made public and available even to users not registered in Deepser.

Note: Knowledge bases published in the Guest Portal are indexed by search engines.

CONFIGURATION KNOWLEDGE BASE – HELP

1 – To make a Knowledge Base visible in the Guest Portal you need to go to the SystemàKnowledge Base section of the Deepser backend and click on the KB that you want to make visible in the Guest Portal. In the Form of the KB configure properly the following fields:

  • Frontend Visibility: Set to ‘YES’ to make the Knowledge Base visible in the Guest Portal.
  • Identifier: This is the name of the resource (in this case the Knowledge Base) that will appear in the URL.

If not set it is automatically calculated when the form is saved.

1b – At this point, the article page will present as the last part of the URL the string previously chosen as identifier.

2 – To then make visible an Article of a Knowledge Base just made visible in the Guest Portal you need to go to the Knowledge Base section of the Deepser backend and click on the KB containing the article you want to make visible in the Guest Portal.

Choose the article and in its Edit form properly configure the following fields:

Frontend Visibility: Set to ‘YES’ to make the item visible in the Guest Portal.

Identifier: It’s the name of the resource (in this case the article of a Knowledge Base) that will appear in the URL. If not set it is automatically calculated when the form is saved.

2b – In the same way of Knowledge Base, also the article will present as last part of the URL the string previously chosen as identifier.

CMS in the Guest Portal

You can change the look and feel and manage the content of the Guest Portal via Deepser’s built-in CMS.

To access the CMS go to the System > Tools > CMS section of the Deepser backend.

PAGES

Through CMS it is possible to define the pages that will belong to the Guest Portal. In its default configuration, Homepage and 404 Not Found are already defined, which are sufficient for an essential configuration.

The tabs that contain the main configurations of a page are Page Information and Design.

To change the configuration of existing pages or create new ones go to the SystemàToolsàCMSàPages section of the Deepser backend.

PAGE INFORMATION

The fields within the Page Information tab have the following meaning:

  • Page Title: page title
  • URL Key: name of the page to be used in the URL
  • Status: status (Active/Inactive)

DESIGN

In the design tab you can choose the page layout from those proposed.

In the Layout Update XML scripting area you can add blocks to the page structure.

STATIC BLOCKS

You can also create new static blocks, or modify existing ones, which will be “injected” into the CMS pages.

To change the configuration of existing blocks or create new ones go to SystemàToolsàCMSàStatic Blocks section of Deepser backend.

The Block Configuration Fields have the following meaning:

  • Block Title: Block Title.
  • Identifier: Block code.
  • Status: Status (Active/Inactive).
  • Content: Area of scripting through which to define the structure of the block.

Cache Management

To increase the performance of the Deepser application, a level of caching was introduced that allows you to obtain the Deepser pages, as well as the CSS or, in general, the content provided by Deepser from a static copy, thus avoiding the need to regenerate them every time a user opens the page.

On some occasions, however, it may be necessary to delete this cached copy to make changes that would otherwise only be visible after the cache has expired. For example, after adding a custom configuration or changing some labels in Deepser.

Delete the cache in Deepser

To delete the cache in Deepser you will need to go to the menu:  System -> Cache Management.

At this point the following screen will open:

Cache Storage Management

This section contains all cache types available in Deepser, which you can enable/disable or refresh.

This can be done with the following available buttons in the top right corner of the form:

Name

Description

Notes

Flush Cache

This button when pressed deletes the cache of Deepser pages.

 

Flush Cache Storage

This button when pressed deletes the cache of both pages and contents of Deepser, so everything will be reloaded.

This button when pressed will ask for a confirmation by opening a popup where you will need to click on “OK” to proceed.

Action / Submit

This command allows you to perform one of the following actions on the modules listed below:

– Refresh (reload the lock cache),

– Enable (enable the lock cache),

– Disable (disable the lock cache).

 

 

Cache Type Explanation

In this section, the complete list of available cache types and their meaning:

Name

Description

Configuration

This module is the cache of Deepser configuration files.

Layouts

This module is the deepser Layout file cache.

Blocks HTML output

This module is the cache of html blocks generated by Deepser.

Translations

This module is the cache of translations in Deepser.

Collections Data

This module is the cache of Deepser collection files.

Web Services Configuration

This module is the cache of the deepser web service configurations.

User collection Data

This module is the cache of user data collections in Deepser.

Device collection Data

This module is the cache of device collections in Deepser.

Additional Cache Management

From this section you can act on CSS/JS cache in Deepser.

Button

Description

Flush JavaScript/CSS Cache

Delete the cache of CSS files and JavaScript files used in the Deepser theme.

Websocket Server Assets

From this section you can act on websocket server for the assets in Deepser.

Button

Description

Check Server Status

This button when pressed allows you to check the status of the Websocket server that distributes the assets in Deepser

Stop Server

This button when pressed allows you to disable the Websocket Server that distributes the Assets in Deepser.

Reboot Server

This button when pressed allows you to reactivate the Websocket Server that distributes the Assets in Deepser.

Chat Websocket Server

From this section you can act on chat websocket server in Deepser.

Button

Description

Check Server Status

This button when pressed allows you to check the status of the Websocket server that manages the chat in Deepser

Stop Server

This button when pressed allows you to disable the Websocket Server that manages the chat in Deepser.

Reboot Server

This button when pressed allows you to reactivate the Websocket Server that manages the chat.

Flow Contexts

From this section you can act on flow context log in Deepser.

Button

Description

Delete Context Log File

This button when pressed allows you to delete the flow log files, the flow log files allow you to see the progress of the flows (only if the flows are enabled)

System Information

From this section, you can view system information for the current server. The information you can check includes the following:

Name

Description

Notes

Deepser Version

Shows the version in which Deepser is running

The moment this document was made the version was 2.4.7.12-7

Disk Space

This indicates disk space usage on the /dev/vda1 partition. The used space out of the total space and the used percentage.

This includes not only the space used by the files but the space taken from the database as well.

CPU/RAM

This indicates the percentage of CPU resources currently in use as well as the used RAM out of the total RAM including the usage percentage

 

Quick Reply

Inside Deepser it is possible to configure various automatic quick replies that can be used to set a predefined text into text-area fields, like comment, email body message and solution description . For example it can be used for a default mail response or for a default reply in a ticket. 

Quick Replies Configuration

Automatic quick replies can be configured by an administrator within various Deepser entities.

To configure automatic quick replies, you can navigate to System-> Quickreply-> Reply and the following screen will appear:

In this example, two different quick replies have been configured, one for the Operation model and one for the Activity model.

To add a new quick reply, just click on the “Add Reply” button at the top right and the following screen will appear:

Below is the list of available fields and their meaning:

Field

Description

Note

Name

The name of the quick reply

In the example, it is called “Example Solution”

Type

The type of quick reply

In the example the type is “Default”

Model

The model inside Deepser where you want to insert the quick reply you are creating

Examples

• If you want to insert the quick reply in the ticket comment, the model is “DeepActivity-Activity”

• If you want to insert the quick response in the ticket solution, the model is “DeepService-Operation”

• If you want to insert the quick reply in the email message, the template is “DeepEmail-Message”

Expression

A query builder that allows you to filter by fields of the chosen model

Examples

• If you want to insert the quick reply in the ticket comment, inside the query builder you will have to filter by Model equal “DeepService-Operation”

Expression (Script)

Section where you can insert filters using custom code

 

Status

The status of the quick reply

You can only use enabled quick replies 

Description

Personalized quick reply message

Note: the code inside the curly brackets is used to retrieve the name of the requester user of the ticket

Quick Reply Use

In order to set automatic and customized reply inside a text-area field, like comment, email body message and solution description of a ticket, you can navigate to the desired field (in our example we are on the “Solution” field into the Operation module, reachable from “Closing Info” Tab).

The following screen will open:

To set a quick reply in the field quickly, you can simply navigate to the “Solution” field and click on “Replies”. From there, you can choose a default reply that has been previously configured (in our example, we only have one configured quick reply in the Operation module, with the type “Default” named “Example Solution”).

Once a quick reply is selected, the field will be automatically filled with the default text configured earlier

You can also customize the automatically inserted text according to your needs.

With a proper configuration, it is possible to insert a quick reply also in a comment on a ticket or within the body of an email.

Mentions

The Mentions functionality in Deepser is accessible to all user types. By default, it is enabled for administrators, agents, and key users, but it remains disabled for end users.

The mentions functionality allows users to tag or reference specific individuals within tickets, comments, or other communication threads. This means you can directly notify someone by using “@” followed by their username, ensuring they see and respond to the issue quickly. This feature improves communication by making sure the right people are informed and can take action promptly. It helps teams work together more effectively, keeps everyone on the same page, and speeds up the problem-solving process. In busy environments where many tasks are being handled at once, mentions help keep everything organized and ensure that no important updates or responsibilities are missed.

Once you have mentioned a user they will be notified via email.

Enable the mentions for End-Users

To enable it you need to go to System->Custom Fields.

Here, you need to go to the module it should be enabled for. Then head inside the description field and go to the Extra Tab. Here you can enable or disable the mentions from the field Mentions (for End Users)

Example  – Comments, Activity Module

 If mentions are needed to be enabled for the comments you need to head to the Activity module.

After opening the module, you need to go to the fields tab and then open the description field configurations.

Go to the Extra Tab and here you can enable or disable the mentions from the field Mentions (for End Users).

Module Creator - Creating a custom module

The “Module Creator” is a component of Deepser designed to allow administrative users to create new custom modules intuitively and through a graphical interface, respecting the Deepser data structure.

Accessing the Module Creator

To access the “Module Creator” you need to go to the menu: System > Module Creator.

Once done, the screen below will open:

Creation

To proceed with the creation, it will then be necessary to click on the “Create new module” button at the top right. The screen that will then appear will be as follows:

General Settings Fields List

Below is a list of the fields in the “General Settings” tab and their meanings:

Field

Description

Module name

Name of the new custom module you want to create.

 

NOTE: It can only contain letters or numbers, but no other characters (no spaces allowed).

Admin menu title

This field indicates the name of the module in the left-hand menu

Icon Class

Through this field it is possible to associate an icon to the new custom module which will then always be displayed in the main menu.

As a result, this field refers to the section that is accessible to all users of the backend.

Icon Color

This field allows you to select the color to be applied to the icon and label displayed on the menu.

As a result, this field refers to the section that is accessible to all users of the backend.

Admin parent menu ID

Through this field it will be possible to decide the exact point in the menu where the operational references of the new module will be displayed.

As a result, this field refers to the section of the new form that is accessible to all users of the backend.

 

The selection within the menu must be made by clicking on the note of the “Select menu parent and position” field.

Admin menu sort order

This read-only field, will be automatically populated based on the selection made through the “Admin parent menu ID” field.

Configuration Icon Class

Field used to associate an icon with the configuration section of the newly created custom form. As a result, this field refers to the section accessible to Deepser admin users.

Configuration Icon Color

Through this field it is possible to select the color to be applied to the icon and the configuration label of the new custom module displayed on the menu.

As a result, this field refers to the section accessible to Deepser admin users.

Configuration Admin parent menu ID

Using this field it will be possible to decide the exact point in the menu where to display the references to the configuration section of the new module.

As a result, this field refers to the section accessible to Deepser admin users.

 

The selection within the menu must be made by clicking on the note of the “Select menu parent and position” field.

Normally, the configuration section is located in the System menu.

Configuration Admin menu sort order

This read-only  field, will be automatically populated based on the selection made through the “Configuration Admin parent menu ID” field.

Module Creator – Selecting the Location in the Menu

To proceed with the selection of the position of the new module within the menu, it is necessary to click on “Select menu parent and position” and then on “Insert here” in the selection popup. Here’s an example:

In the example above, according to the screenshot, the new module would be inserted between the “Service” and “IT Asset” sections of the menu.

Saving the module

Once you have finished filling in the fields of the “General Settings” tab, you need to navigate to the “Entities” tab because to proceed with saving, it is necessary for the new form to have at least one entity associated with it. To accomplish this, simply click on the “Add entity” button located at the top right corner. Each new entity is divided into “Settings” and “Fields/Attributes:

Settings

Through the “Settings” section, it will be possible to enable modules for some of Deepser’s standard management tasks, such as the ability to associate categories, configure types, and more.

To proceed to fully view all the fields in the “Settings” or “Fields / Attribute” section, click on the “+” icon next to them. Below is the screenshot of all the configurable fields for the “Settings” section:

Settings Fields

Below is a list of the fields in the “Settings” section and their meanings:

Field

Description

Label singular

Label of the new custom module in singular form.

Label plural

Label of the new custom module in plural form.

Entity code singular

The value entered in this field (which should refer to the name of the new module) will be used for the names of variables, files, and tables within Deepser. This approach simplifies the process of making configurations via the scripting area if necessary. Keep in mind that in this field, the value should be specified in singular form.

Entity code plural

It serves the same purpose as the “Entity code singular” field, except that in this case you need to specify the value in plural form.

Manage Advanced Permissions with Groups and Companies

If you set this value to YES, the “Owner Group”, “Owner Company”, and “Owner User” fields will be created. Through these fields it will be possible to manage the entity of the new module through custom group rules.

Manage Advanced Accesses

Setting this field to YES will create the “Access Group”, “Access Companies”, and “Access Users” fields that are typically used to “expand” visibility for the records.

Associate Categories

Setting this field to YES will create the fields “category1”, “category2”, “category3”, “category4”, and you will then be able to associate the standard Deepser categories with the entity of this new module as well.

Add Type Entity

By setting this field to YES, the “Type” field will be created and you will then be able to manage the types on this entity of the new module.

Manage History Changes

Setting this field to YES will create the “History Changes” field for this new form. Through this field it will be possible to have the history of all the changes made on a record of that entity.

Visible on Portal

By setting this field to YES, it will be possible to manage the new entity also on the end customer portal side.

Add Routing

By setting this field to YES, you will also be able to use the new entity in Deepser routing rules.

Use Icon

Setting this field to YES will create an “icon” selection field, enabling you to associate an icon to the new entity.

Icon Class

This field allows you to select an icon to display in the menu for this new entity.

Icon Color

Field linked to the previous “Icon Class” that allows you to select a color for the icon and label of the entity.

Fields/Attributes

Once you have finished filling in the “Settings” section, you will need to consider creating new dedicated fields for the new entity. To access the details of the “Fields / Attribute” section, you will need to click on the “+” icon. From here, you can add new fields to the entity. To do this, simply click on the “Add field / attribute” button. Here’s the screenshot:

Fields/Attributes List

Below is the list of configurable fields for a new field/attribute:

Field

Description

Attribute code

This field indicates the field code that will be used for tables and variables in Deepser. Therefore, it is necessary to adhere to some guidelines:

– The first character must be a letter

– Only lowercase letters, numbers, or underscores (_) can be entered

– Reserved names such as “data” or “child” cannot be used.

Attribute label

This field indicates the label of the field that will be displayed in the forms.

Attribute Type

Through this field you can indicate the type of field you want to create.

Acts as name

Each entity must have an attribute to function as its “Name”. This attribute will be used to distinguish between different entities and will also appear in dropdown menus with entities. This option is only available for text, numeric, and decimal attributes.

 

NOTE: Only one of the defined fields can have this flag. Normally you should use it for the main field of the entity you’re creating.

Required

If set to Yes, it indicates a required field.

Use WYSIWYG editor

If set to Yes, it indicates that the field can be managed by editor.

The field is activated only if the type of field created is “Textarea”.

Show in admin grid

When set to Yes, includes the new field in the entity’s default grid.

Options in select

Useful field to indicate a list of values for select or multiselect fields. All values entered in this field must be separated by a pipe (|) delimiter. If you want to include an empty option as the first value, you must start with a pipe symbol.

Saving the fields/attributes

Once you have completed all the main configurations and entered all the fields of your interest, you can proceed with saving the new custom module. You can then proceed by clicking on “Save” or “Save and Continue Edit”.

Installing the module

Once saved, it will then be possible to install the new module using the dedicated “Install” button:

Once the installation is complete, you will find the new module and its entity in the Deepser menu.

Regenerate Button

Within the configuration of the new custom module, a new “Regenerate” button will appear:

The button in question will be used to regenerate the module if its configuration is changed. For example, if a feature is enabled on one of its entities or if a new field is simply added, clicking on the “Regenerate” button will allow you to propagate and apply the changes.

The button will proceed to make a backup of the data entered so far in the custom module, to delete and recreate the structure of the module and finally to restore the data previously entered.

Uninstall Button

After installation, in addition to the regenerate button, the “Uninstall” button will also appear. By clicking on that button, the entire configuration of the custom module and the custom module itself (including the records saved within it) will be permanently deleted. You will then not be able to recover the data.

Import/Export

Through “Module Creator”, it is also possible to export and import the entire configuration of a created module.

In fact, once the module configuration has been saved, returning to the main list of custom module management (again from the > Module Creator System), an “Export” column will be available on each individual configuration record and an “import” button through which it will be possible to export and import the configuration of a module.

Below is an explanatory screenshot:

Email Integration

Email integation is a very important module for the organizations that adopt a Service Desk software, in order to interact with their customers and to improve the collaboration between team members.

Deepser is designed to provide a web platform in order to avoid a large number of email messages and so defining a shared and orderly way to manage a service.

It’s clear, however, that the email notifications to customers (or operators) can be a plus for our service.

In addition to set up a web portal, we can give other communication channels like emails to that users who want the “security” of an email confirmation after their request.

Fundamental entities of the Deepser email integration are:

  • Mailbox: the email addresses managed to send or receive notifications.
  • Events: talking about outgoing emails, an event is used to define when sending a notification.
    It is possible to define an infinite number of events to notify our users.
  • Templates: the templates (subject, body and layout) of the outgoing emails.
  • Messages: the email messages sent or received by the system. This entity it’s not directly visible in the Email module, because every message (and their attachments) are only visibile inside the forms of the entity they are linked to (eg: a message related to an Operation in the module “Service”, or an email sent about an asset of the CMDB).

Email Integration in Service Management

Emails are integrated into the operations of service management.

With the appropriate configuration of email events, messages are automatically generated to notify customers, technicians or operators.

Through the message subject Deepser can also recognize incoming emails that refer to an existing entity in Deepser and associates them.

In order to see all the email messages associated with, for example, a service operation and/or its related entities (Comments, Worklog or Task) there is a dedicated field, the Email List.

By default this field is added to the operations screen, in the Email tab.

From the Email List field you can understand which emails are incoming and which are outgoing.

Email List also shows: subject, date of receipt or sending, sender and recipients.

By clicking on the “lens” icon, you can view the message body.

COMMENTS AND EMAIL

Most of the time you want that to each comment, added to a service operation, corresponds an email notification send to other actors. Deepser proposes this configuration as default.

If, for example, a technician in charge of the resolution of an issue needs more information from the user, he can request it by adding a comment inside the issue.

Deepser then sends an email, containing the technician’s request, to the user who will respond with the required information.

The user’s email will be “linked” with the issue and a comment will be created from its content.

The technician will receive a notification from Deepser containing the user’s response and will then be able to complete the issue resolution activities and close it.

Enable Embedded Images on Message Body

In Deepser, by default, images, embedded in the body of incoming emails, are saved as attachments to the email message and not included in the body and saved, for example, within the Description field.

Images can still be viewed from the Email List grid, in the operation form, in the Attachments column.

NOTE: By enabling this option the size of the Database can increase considerably over time, for this reason by default it is disabled.

To enable this option go to the system configuration menu: System->Configuration->General->Email->Attachment

Set ‘Embedded Images on Message Body‘ option to ‘Yes‘.

Mailbox

Using Mailboxes, Deepser can Receive and Process Emails, send Notifications, etc.

There are no limits about the number of email addresses that can be integrated, nor on the provider.

 

Configuring an Outgoing Mailbox

Mailboxes are one of the fundamental entities in email integration.

In order to send emails to your users, in fact, you need to define an outgoing mailbox, in this guide we are going to explain the procedure for its setup.

CONFIGURATION

To configure a mailbox in Deepser, in the backend navigation menu, navigate to the System->Tools->Email->Mailbox section.

The grid in this section shows mailboxes already configured in Deepser.

To configure a new mailbox click on the ‘+ Add Mailbox‘ button in the top right corner.

At this point the mailbox configuration form will open.

Once the mailbox type has been set, in this case ‘OUT‘, all fields for the outgoing mailbox configuration will be loaded dynamically.

The fields in the form have the following meaning:

TABFIELDMEANING
GENERAL DATANameName of the mailbox. It is a descriptive field used in the system to display the mailbox.
 TypeIN or OUT (IN to receive emails, OUT to send emails).
 StatusIf “Disabled” the email integrations will not be active.
 Email DisplayThe displayed email address. It is not the username. The username is used to access the email, this field is only the displayed email address if our server allows us to use a different email address for the outgoing messages.
 Display NameThe name displayed in the “From” field of the emails (eg: Your Service Desk).
 HostThe address of the mailserver. It depends on your provider or mailserver.
 DoorPort for the connection to the mailserver.
 EncryptionEncryption of the connection to the mailserver. It depends on your provider or mailserver.
 User NameUser name (usually the email address) to connect to our mailbox.
 PasswordPassword to connect to our mailbox.
 ProtocolProtocol to send emails (SMTP or OWA). It depends on your provider or mailserver.
 OAuth ClientOAuth2 client used for the  authentication on services that require it.
SITEMA DATAPrefixIt’s the prefix to prepend to the unique field of the record (usually the ID) sent by email. The Prefix is mainly used in the Subject of the email by the incoming integration (mailbox IN), to tell Deepser if it has to create a new record or to update an existing one. To give an example, if we are sendind an email for a Service Operation record, we can define that the prefix is “TICKET#”. By doing so, the emails will be sent with the subject “TICKET#ID” (where ID is the unique number of the Service Operation). If the user answers that email must not delete this text, to make Deepser aware of the record the email is referring to.
 Allowed EmailsIt tells if emails can be sent only to users registerd in the system or to any email address.
 Is Default OutgoingIt tells if the email is the default to send notifications. Deepser lets configure an infinite number of mailboxes, but the system needs to know which is the default one to send notifications. Every Service Operation record, for example, contains a field called Mailbox ID, that represents the email address to send the notifications for that record. If this field is not filled, then the emails will be sent using the Default Mailbox.
 Exclude ExpressionIn this field you can insert a regular expression in order to block emails whose recipients match the defined expression.
ADVANCEDCustom CodeCustom PHP code executed after an email has been sent. It is possible to configure this field to trigger custom events. For example, if we wanted to update a counter of the reinders or update a specific entity of Deepser, we could exploit the customization of this field.

Once the form has been filled and the configuration saved, click on the ‘Check‘ button, top right, to test the configuration.

If the mailbox has been configured correctly you will see a message of successful connection, otherwise an error message.

Configuring an Incoming Mailbox

To be able to create entities, from incoming emails, it is necessary to define an incoming mailbox, and then associate this mailbox to related email rules.

This guide will explain how to configure an IN mailbox.

Important Note: based on the settings of your email server, all incoming messages could be deleted after Deepser has processed them. This is the default behaviour of the software with email servers like Exchange, Standard SMTP Servers, etc.

Be very careful when configuring the incoming email integration, do a test and a backup. Remember also that Deepser processes all the emails in the inbox, so if the mailbox is full of messages (eg: the first time we run the integration) a lot of records could be created.

To avoid this situations, not directly caused by Deepser, we advise always to do a test on mailboxes with few messages.

CONFIGURATION

To configure a mailbox within Deepser, in the backend navigation menu, navigate to the System->Tools->Email->Mailbox section.

The grid in this section shows already configured mailboxes.

To configure a new mailbox click on the ‘+ Add Mailbox‘ button in the top right corner.

At this point the mailbox configuration form will appear.

Once the mailbox type has been set, in this case ‘IN‘, all the relevant fields will be loaded dynamically.

The fields in the form have the following meaning:

TABFIELDMEANING
GENERAL DATANameName of the mailbox. It is the name used in the select-boxes.
 TypeIN o OUT (IN to receive emails, OUT to send).
 StatusIf “Disabled” the integration will not be considered by the system.
 HostAddress of the mailserver.
 PortPort for the connection to the mailserver.
 EncryptionEncryption of the connection..
 UsernameUser name to read the mailbox (usually it is the email or the Exchange user associated to that mailbox).
 PasswordPassword to login to the mailbox.
 ProtocolProtocol to get the emails (POP3, IMAP or OWA).
 OAuth ClientOAuth2 client used for the authentication, if required.
SITEMA DATAModelThe field Model represents the entity of Deepser in which to look for a record linked to the received emails. If we set for example DeepService – Operation the mailbox will create and update records of Operations. If we set DeepAdmin – User the emails will used to create or update users.
 Model FieldIt is the field of the entity Model where to check if a record already exists. If we set the ID (field: entity_id), then the check will be done on entity_id (unique ID) of the Operations.
 PrefixIt’s the prefix we prepend to the Model Field, to search the record. If we set the Model Field equals entity_id of the Operation, then the email integration verifies the subject of the email: if after the Prefix there’s an ID of a record already in the system. After the expression Prefix and until the first blank space, the ID of the model will be searched. Thus, if we set the field Prefix with the value TICKET# and the Model Field with the value entity_id, if we receive an email with subject TICKET#70, then Deepser looks for an Operation with ID 70. If Deepser finds that record, then the record is updated and the rules applyed to update the record are that in the Update Expression field. If we receive an email with a subject Hey this is a new ticket then Deepser creates a new record, following the rules in the field Create Expression.
 Outgoing Email BoxWe can teel the system that for every record created using this mailbox we will use the specific outgoing mailbox to send notifications.
 Apply Email RulesIf yes related email rules are executed.
 Allowed EmailsIf we can receive email from all emails or only from registerd users. Ignored mails will be deleted.
 Spam ExpressionIn this field it’s possible to define a regular expression to check the objects of incoming mails in case they should be identified as spam. If the emails are ignored they are deleted from the inbox.
ADVANCEDCron ExpressionCron Expression that defines the frequency of the scan of Deepser. If this expression is not set, this mailbox will not be processed by Deepser.
 Processed onDate and time of the last scan of the mailbox.
 Custom CodePHP custom code run after the email has been received. It is possible to configure this field to trigger custom events after the email has been received. For example, if we want to receive a counter of the reminders or to update a specific entity of Deepser after we have received the email, we can customize this field to do that.

Once the form has been filled and the configuration saved, click on the ‘Check‘ button, top right, to test the configuration.

If the mailbox has been configured correctly you will see a message of successful connection, otherwise an error message.

OAuth Client for Email Integration

Some systems require web applications, such as Deepser, to perform authorization before they can use their services.

Deepser allows you to configure multiple OAuth clients in order to authorize it , through the OAuth2 protocol, on different services.

CONFIGURATION

To configure an OAuth client in Deepser, navigate to the System-> Tools->OAuth->Client section.

You will see a grid containing all oauth clients defined as Deepser.

To configure a new client click on the ‘+ Add Client’ button in the top right corner.

A new OAuth Client can be also created and configured from the configuration form of a mailbox.

Under the OAuth Client field, of the Select type, whose options are the already configured clients, clicking on the ‘+’ icon allows you to create a new client, while clicking on the ‘pencil‘ icon allows you to modify the configuration of the selected client.

The fields of the configuration form of an OAuth client are listed and explained below:

FIELDMEANING
Redirect UriDeepser Url from which Deepser which will send requests to the provider. The URL must be authorized in the administration panel of provider. The URL will appear once the client is saved. After saving, the ‘Validate‘ button will appear, by ckicking it you can authorize the client once its configuration is complete.
NameClient name. It represents a descriptive field with which the client will be displayed in the system.
ProviderProvider: Google, Azure, Generic. If you use Google or Azure as a provider the only other fields that must be filled are Client ID, Client Secret and status. Generic value is used to configure the authentication to all other providers.
Client IDPublic identifier for applications. It is provided by the provider, usually when a new application is authorized.
Client SecretSecret part of the authentication credentials. It is provided by the provider.
TypeType of data you want to access/recover.
ScopeScopes to which the application requires access. No need to fill it for Google or Azure providers, default values will be used.
Url AuthorizeIt is the ‘base URL’ of the Identity Provider that manages OAuth 2 authentication. No need to fill it for Google or Azure providers, default values will be used.
Url Access TokenThis is the ‘base URL’ to which the parameters for requesting the authentication token are added (post-authorization step). No need to fill it for Google or Azure providers, default values will be used.
ProxyIP address and port of any used proxy. It is not necessary for Google or Azure providers, default values will be used.
VerifyIf a proxy has been configured you can enable or disable the SSL check. No need to fill it for Google or Azure providers, default values will be used.
StatusIf ‘disabled’ the client is not active.
Scope Separator CharCharacter used to separate different scopes. Used during the construction of the request url. No need to fill it for Google or Azure providers, default values will be used.
Endpoint User DataIn case the OAuth configuration is User type and the User Data Source is set to ‘Endpoint’, once the authentication is done with the Identity Provider the user data is retrieved by connecting to this endpoint. No need to fill it for Google or Azure providers, default values will be used. No need to fill it for Email Box type.
Related LDAPsAny LDAP integrations already configured, whose users must be linked. No need to fill it for Email Box type, the default values will be used.
Username AttributeAttribute (field) that desctibe the user’s username. No need to fill it for Google or Azure providers, default values will be used. No need to fill it for Email Box type.
User FieldsMaps the user (Deepser entity) attributes to those retrieved from the specified user data endpoint. No need to fill it for Google or Azure providers, default values will be used. No need to fill it for Email Box type.
User Create ExpressionPHP code for configuring the user creation, for example in case of an SSO integration. No need to fill it for Email Box type.
Login Button CaptionButton label for access via SSO. No need to fill it for Email Box type.
Login Button IconIcon displayed on the SSO authentication button. No need to fill it for Email Box type.
Access TokenThis field is not filled out in the form for security reasons. It contains the serialized access token.
Original Access TokenThis field is not filled out in the form for security reasons. It contains the serialized access token.

Once the form has been completed and the OAuth client configuration has been re-saved, you can validate it.

Just click on the ‘Validate‘ button that will appear once the client is saved for the first time.

Authenticate on Provider through the form that will appear, once logged in the client is authorized.

Email Loop Management Tool

In Deepser there is an integrated tool that allows you to mitigate and block email loops, blocking the receipt of emails from email addresses that have sent a large (configurable) number of emails in a defined time interval.

 

EMAIL LOOP MANAGEMENT TOOL ENABLING GUIDE

To enable the Loop email management tool, you will need to go to the System-> Tools -> Email->Mailbox menu

Once here we will have to go to the configuration of the email input boxes, if it is necessary to configure the tool for multiple email boxes it will be necessary to follow this guide for each entry box.

You will now need to click on the edit button of the form template in the upper left part of the page:

At this point we will have to go to configure a new tab “Email Loop Configuration”, the name can be configured if necessary.

To configure the new tab, you will need to right-click on the tab item and click “New Tab”.

Now you will need to click on the Newly created “New Tab” entry:

Here we are going to change the “Label” field with the name we want to give to this new tab, in our case Email Loop Configuration

Now we will have to click the “SAVE” button to save to the configuration.

At this point we will have to go to configure a new Fieldset “Email Loop Settings”, the name can be configured if necessary.

To configure the new tab, you will need to right-click on the tab item and click “New Fieldset”.

To rename the fieldset you will need to click on the new fieldset just created, at this point you can rename the fieldset by changing the head present in the campo at the top center of the page:

In our case we will rename it to “Email Loop Settings”.

At this point we must enter the following fields in this fieldset:

  • Allowed Messages Interval
  • Allowed Messages Number
  • Lock Duration
  • Whitelist Expression
  • Blacklist
  • Message Logs

Once done it will be possible to change the width of the fields through their settings in order to make it easier to fill them in and consult, the final result will have to look like this:

Finally, we will have to go and click the “SAVE” button to save the changes to the form template.

 

EXPLANATION FIELDS EMAIL LOOP MANAGEMENT TOOL

After configuring the form as described in the previous step we will have in the “Email Loop Configuration” tab a structure similar to this:

Below is the list of fields with their description:

FieldDescriptionNotes
Allowed Messages IntervalThe time interval in which the number of messages received from an email address will be evaluated 
Allowed Messages NumberNumber of messages allowed per email address in the time interval defined in the “Allowed Messages Interval” field 
Lock DurationThe duration of the block on receiving messages if an email loop is detected. 
Whitelist Expressionthis field is a regular expression (regex) which will instruct the system to exclude all email addresses that match this regular expression 
BlacklistHere you will see the list of blocked email addresses and until they are blocked 
Message LogsHere you will see the list of blocked email messages 
 

EXAMPLE EMAIL LOOP MANAGEMENT TOOL CONFIGURATION

Suppose you want to configure the email management tool to block all email addresses that send more than 30 messages in 5, minutes for 15 minutes but you want to exclude from this rule all addresses that belong to the domain example.com eg.  test@example.com

To do this you will need to configure the fields as follows:

  • Allowed Messages Interval set to 5 minutes
  • Allowed Messages Number set to 30
  • Lock Duration set to 15 minutes
  • Expression whitelist set to:
[\w+|\.] +@example\.com

Below is an image of the final result:

At this point you will need to click on “Save” or “Apply” to save to the configuration

AZURE OAUTH CLIENT

This guide explains step-by-step how to set up a new OAuth client to integrate Office365 with Deepser. To do this you will need to create a new APP Registration in Azure.

Before starting the setup, it is necessary to retrieve your Tenant ID, which is required for the first step of the configuration.

You can do it searching and accessing Microsoft Entra ID Overview page:

OAUTH CLIENT CREATION IN DEEPSER

In Deepser, go to the menu item System -> Tools -> Oauth -> Client.
 Then click the blue Add Client button.

Then set:

  • Name
  • Provider: Azure
  • Type: Mailbox
  • Tenant ID

Then click Apply or Save.

Once the save is completed, the redirect URI will be generated:

We can then proceed to copy the redirect URI that we will use in the next configuration step.

CREATING YOUR APP ON AZURE

Go to the Azure portal and sign in with your Office 365 account.

Once logged in, click on App Registrations.

Then click New Registration.

Give a name to the application and in Supported Account Types, set the Single Tenant (first item).

Scrolling, set the Redirect URI: set Web in the first drop-down menu.

In the second field you need to paste the URI provided by the OAuth client provided in Deepser.
Then return to the configuration of the OAuth client in Deepser and copy the URI that we find under the Validate button (the URI will be generated in Deepser after the first save of the client).

Then return to the application registration in Azure and paste the URI.
Finally, click on Register.

AZURE APP CONFIGURATION

Once the app is created, click on Authentication, item in the left menu.

Scroll down the page and tick the access tokens and ID tokens.
Then click Save.

Go now to the Certificates and Secrets
 item on the side menu. Click on the Client Secrets tab and generate a new Client Secret through the New Secret Client button.

Then enter a Description, a Deadline and click Add.

Once the Client Secret is generated you need to copy its Value and paste it on the Client Secret of the OAuth Client into Deepser.
Attention: the value of the Client Secret will be viewable only at the first generation. After that it will be censored and it will no longer be possible to view or copy it.

In the Client ID in Deepser you need to paste the Application ID.
The ID of the application can be retrieved in the Menu item Overview.

Then save the changes to Deepser.

Go now to the API permissions through the API Permissions in Azure menu item and click Add a permission.

In the Microsoft API tab, select the Microsoft Graph APIs.

Then select Delegated Permissions.
Then tick the entries of the following permissions:

  • Offline_access
  • Mail.ReadWrite
  • Mail.Send
  • IMAP.AccessAsUser.All (optional if using POP)
  • Pop.AccessAsUser.All (optional if using IMAP)
  • SMTP.Send

You can search for these permissions by searching for these permissions.
Once selected, click Add Permissions.

Once you have added permissions, you must grant administrator consent via the Grant Admin Consent for Deepser button. Confirm by clicking Yes in the popup.

OAUTH CLIENT VALIDATION

Once the Client has been configured, it must be validated through the appropriate Validate button.

NOTE: The user who validates the Client must have an active Office 365 license and must be able to access the mailboxes on which you want to use the OAuth client.

Also make sure that the user with whom you are validating the Client has enabled the following protocols in the user settings with which you will validate the client within the admin area in Office 365:

  • IMAP
  • Pop
  • Authenticated SMTP.

If you use shared mailboxes, make sure that IMAP and POP services are enabled in them.

If the validation is successful, we will be returned to the Client configuration with a green message at the top that tells us the successful completion of the validation.

Now go to the configuration of the incoming box in Deepser via the menu item System -> Tools -> Email -> Mailbox and select the incoming box.

In the OAuth Client field, select the OAuth Client that you just configured and validated.

Then save your changes.

To verify that the box is working correctly, you can use the Check button.
If everything works, the Check will return a message in green with the message “Connection Successful”.

Google Oauth Configuration

Create an OAuth Client in Deepser for Mailbox

In the Deepser Configuration, navigate to System > Tools > OAuth > Client > Add Client:

Enter a name, define the type  as  Mailbox, set the provider as Google and save.

Once saved, copy the generated Redirect URL.

Go to the Google Cloud Platform, and log in. Once this is done, click on  the  menu at the top where all the projects are listed.

A window will open where you can create a new project using the New Project button. All you have to do is give your new project a name and click on the Create button.

To enter the newly created project  , repeat the process above:  click on the menu that groups all the projects and click on the name of the newly created project to start the configuration.

Once you have entered the project, click  on the APIs & Services (1) > OAuth Consent Screen  (2) section in the menu on the left.

In User Type select External and proceed by clicking Create.

Give the application a name, enter the email used for access  in User Support Email and in Developer Contact Information. Proceed to Save & Continue.

Under Scopes, press the Add or Remove Scopes button.

In the form below the paragraph Add Manually, copy and paste the following address https://mail.google.com/. Then  click Add to Table, and then  click Update. Then click save and  continue to continue.

In  the Trial Users section, click on Add User and enter the email address with which you logged in to the platform.

Now go to  the Credentials  section of the menu on the left and create a new Oauth Client ID through the Create Credentials button.

In the drop-down menu, select OAuth Client ID.

Select in  the application type Web Application, give it a name, and under Authorized Redirect URIs,  paste the URI that you previously generated and copied. Finally, click Create button.

The Client  ID  and Client Secret will be generated and copied and entered into the respective fields of the OAuth Client previously started to configure in Deepser.

Once saved, proceed with the Client Validation by clicking on the Validate button.

Then log in and click Continue.

Tick the boxes regarding the read/write permission of Google Mail and click Continue.

If all the steps have been carried out correctly, the Oauth Client will be validated and active.

Email Rules

INTRODUCTION

After you have configured an incoming mailbox you can associate it with the Email Rules.

When receiving an email, according to the logic configured in the rules, entities can be created in Deepser.

A typical case is the one in which you want to create, from the received emails, operations (ticket), or comments associated with them.

APPLICATION RULES

You can specify when execute the rule:

  • On Create: Deepser recognizes the message as the beginning of a new thread, i.e. the email subject does not contain the specified prefix (defined in the incoming mailbox configuration) or the ID is not associated with any entity of the model indicated as the main mode (in the incoming mailbox configuration).
  • On Update: Deepser recognizes the message as related to an already existing entity.
  • Always: For each message.

PRIORITY

To each rule can be assigned a priority, that determines the rules execution order.

The higher the value, the sooner it will be executed.

Only one rule can be executed for each message, so the first rule of the stack, whose filter condition is checked. is executed, remainings are ignored.

So it is very important to choose correctly the priority of each rule. Especially when you have multiple email rules not mutually exclusive.

EMAIL RULE CREATION

You can create new email rules in two different ways: actually create it or duplicate an existing one.

CREATING AN EMAIL RULE

Go to the Emailà Toolsà Systemà Rule and click on the ‘+ Add Rule‘ button in the top right corner.

DUPLICATE A RULE

You can create an email rule by duplicating an existing one. By doing so, the new rule will inherit all configurations of the original one. They will only differ for the name to which the suffix “(copy)” will be added.

To duplicate an existing rule, from its form click on the ‘Duplicate Rule‘ button in the top right corner.

Email Rule Configuration

To configure an Email Rule go the Rule Email->Tools->System section.

Click on a rule already defined (in grid) or the ‘+Add Rule‘ button.

At this point the configuration form will be displayed.

The form fields have the following meaning

FIELDSIGNIFIED
NameRule name. Descriptive field with which the rules will be displayed in the system.
PriorityPriority assigned to the rule. The higher its value the sooner it is evaluated in the applicable rule queue.
MailboxMailbox for which the rule must be applied.
Apply OnSelect which allows you to specify when a rule is to be applied: Always, On Create, On Update.
StatusThe status (enabled/disabled). If “Disabled” the rule will not be active.
Email Message FilterIn this field, through the query builder or by entering PHP code in the scripting area, you can specify the conditions that the incoming message must meet. If the conditions are met the rule is executed.
Set main model valuesIn this field, through the query builder or by inserting PHP code in the scripting area, it is possible to specify how the fields of the main template (defined in the mailbox configuration) should be valued when the rule is executed.
Related Model AliasThis field, if filled, defines the model of the “weak” entities to put in relationship with the main model. A typical case of use is in the ‘On Update’ events, when a new message doesn’t have to create an operation but a comment related to the existing one.
Set related model valuesIn this field, through the query builder or by inserting PHP code in the scripting area, you can specify how the fields of the related model should be valued.

Advanced Email Rule Configuration

In case you need to configure Advanced Email Rules you can define them using PHP code instead of using the available query builder.

You can insert custom code in the ‘Email Messages Filter‘ ‘Set Main Model Values‘ and ‘Set Related Model Values‘ fields, to access their scripting area just click on the </> button.

Avoid Duplicate Tickets By Email

In this example we want to configure a custom Email Rule, in order not to create a new operation, if one already exists in open status.

The “duplicate” email will be added as a comment to the already open ticket.

STEP1: SET THE MAIN FIELDS OF THE RULE

As a first step set the basic fields of the rule: Name, Priority, Mailbox, Status.

Set the ‘Apply On‘ field to ‘On Create‘, this will intercept all those emails that are not recognized as part of an already existing thread (for example through the pattern TICKET#).

Set, in the field ‘Related Model Alais‘ the model ‘DeepActivity – Activity‘, to sepcify that a comment will be added to an operation.

STEP2: CONFIGURE THE FILTER

Messages that meet all of the following conditions, when compared to an operation, will be considered duplicates:

  • The sender is also the Requester User of the operation
  • The subject of the email is the title of the ticket
  • The operation is, at that moment, not closed/eliminated

To configure the filter, enter the following PHP code in the ‘Email Messages Filter‘ field

				
					//JSON that manage what the querybuilder shows in this case 'Body Text equal READ CODE ABOVE'
/** START_RULES
{"condition":"AND","rules":[{"id":"body_text","field":"body_text","type":"string","input":"text",
 "operator":"equal","value":"READ CODE ABOVE"}],"valid":true}
END_RULES */
 
//parse the sender and normalize the email address
$fromString = '';
$from = Deep::helper('deep_util')->parseEmailString($this->getMessage()->getFrom());
if (count($from)){
    //get normalized address
    $fromString = array_keys($from)[0];
    //load the user corresponding to that email address
    $fromUser = Deep::getModel('deep_admin/user')->loadByEmail($fromString);
    //if exists retreive his username
    $fromUsername = $fromUser && $fromUser->getId() ? $fromUser->getUsername() : $fromString;
    //retreive the message subject
    $mailSubject = $this->getMessage()->getSubject();
    //retreive all open status
    $openStatusValues = Deep::helper("deep_list")->getStatusValues(
        Deep_Service_Model_Operation::LIST_CODE_STATUS,
        Deep_List_Model_Listclass::TYPE_OPEN);
    //retrieve a collection of operations that meet the following requirements
    $operations = Deep::getResourceModel('deep_service/operation_collection')
        ->addFieldToFilter('status',['in' => $openStatusValues])
        ->addFieldToFilter('requester_username',['eq' => $fromUsername])
        ->addFieldToFilter('title',['eq' => $mailSubject]);
    //if at least one exists
    if(count($operations)){
        //save its id on the request
        Deep::register('custom_email_rule_operation_model_id',$operations->getFirstItem()->getId());
        //save sender username on the request
        Deep::register('custom_email_rule_message_from_username',$fromUsername);
        //return true means that the message is a duplicate
        return true;
        //then the code in the field 'Set Main Model Values' is executed
    }
}
//not all the conditions to define the message as duplicate have been met
return false;
				
			

STEP3: CONFIGURE/SET THE MAIN MODEL

Through the field ‘Set Main Model Values‘ set the operation, retrieved in the field ‘Email Messages Filter”, as main model to which the message must be added as comment.

Insert the following PHP code in the scripting area.

				
					//JSON that manage what the querybuilder shows in this case 'Description equal READ CODE ABOVE'
/** START_RULES
{"condition":"AND","rules":[{"id":"description","field":"description","type":"string","input":"text",
"operator":"equal","value":"READ CODE ABOVE"}],"valid":true}
END_RULES */
 
//set message as non-creator. Because it doesn't create a new main model.
$this->getMessage()->setIsCreator(0);
//retreive operation id from the request (added in the code of the 'Email Messages Filter' field)
$operationId = Deep::registry('custom_email_rule_operation_model_id');
//load the operation and set it as main model
$this->setModel(Deep::getModel('deep_service/operation')->load($operationId));
return $this->getModel();
				
			

STEP4: CONFIGURE COMMENT CREATION

Through the field ‘Set Related Model Values‘ configure the creation of the comment in relation with the main model, set in the field ‘Set Main Model Values‘.

Inserting the following PHP code in the scripting area.

				
					//JSON that manage what the querybuilder shows in this case 'Description equal READ CODE ABOVE'
/** START_RULES
{"condition":"AND","rules":[{"id":"description","field":"description","type":"string","input":"text",
 "operator":"equal","value":"READ CODE ABOVE"}],"valid":true}
END_RULES */
//retreive operation id from the request (added in the code of the 'Email Messages Filter' field)
$operationId = Deep::registry('custom_email_rule_operation_model_id');
//delete operation id from the request
Deep::unregister('custom_email_rule_operation_model_id');
//retreive sender username from the request (added in the code of the 'Email Messages Filter' field)
$fromUsername = Deep::registry('custom_email_rule_message_from_username');
//delete sender username from the request
Deep::unregister('custom_email_rule_message_from_username');
//Create new Activity
$comment = Deep::getModel('deep_activity/activity');
//Set type Comment (1=>Comment, 2=>Worklog)
$comment->setType(1);
//Set the main model (operation in this example) alias
$comment->setModelAlias('deep_service/operation');
//set the id of the operation to which the comment should be added
$comment->setModelId($operationId);
//set the email body as Comment description
$comment->setDescription($this->getMessage()->getBody());
//set sender as user who created the comment
$comment->setCreatedBy($fromUsername);
//set comment as visible to end users
$comment->setPortalVisibility(1);
//save the comment
$comment->save();
				
			

Managing additional Email recipients

In this example you want to create a custom Email Rule to store all the recipients of an email that generates a new operation, and then eventually add them in Cc to the notifications generated during its life cycle.

Two new custom fields will be created in the operations, one to manage recipients who are also registered users in Deepser, the other to store only email addresses.

STEP1: CREATE CUSTOM FIELD FOR REGISTERED USERS IN DEEPSER

Create a custom field in the DeepService – Operation model with the following characteristics:

  • Column Name: cust_operation_cc_registered
  • Label: Additional Recipients
  • Column Type: Don’t create DB clumn
  • Element Type: Userassociation

STEP2: CREATE CUSTOM FIELD FOR UNREGISTERED USERS IN DEEPSER

Create a custom field in the DeepService – Operation model with the following characteristics:

  • Column Name: cust_operation_cc_unregistered
  • Label: Additional Recipients (Not Registered)
  • Column Type: Text area
  • Element Type: Textarea

STEP3: EMAIL RULE CREATION

 Create a new Email Rule, set name, priority (higher than a possible default rule) and status ‘Enabled’.

Set, in the ‘Apply On’ field the value ‘On Create‘ to indicate that the Email Rule should be executed if the message does not belong to an existing thread.

STEP4: EMAIL RULE CONFIGURATION

In the “Set Main Model Values” Query Builder, Set the following values:

 

Insert in the scripting area of the ‘Set Main Model Values‘ field the following PHP code, which implements the logic for saving, on the operation custom fields, any additional recipients.

				
					/**
 * Additional Recipient Managment
 **/
//retreive already parsed Tos
$to = Deep::helper('deep_util')->parseEmailString($this->getMessage()->getTo());
 
//retreive already parsed Ccs
$cc = Deep::helper('deep_util')->parseEmailString($this->getMessage()->getCc());
 
if((!is_null($cc) && is_array($cc) && !is_null($to) && is_array($to) )) {
    //merge to and cc arrays, and change keys case
    $recipients = array_change_key_case(array_merge($to,$cc), CASE_LOWER);
      
    //exclude incoming mailboxes defined in deepser to avoid loops
    $mailboxCollection = Deep::getResourceModel('deep_email/mailbox_collection')
        ->addFieldToFilter('type',['eq' => 1]);
         
    foreach($mailboxCollection as $mailbox){
        if($mailbox->getUsername()){
            unset($recipients[strtolower($mailbox->getUsername())]);
        }
    }
     
    //manual exclusion other emailboxes that forward emails to deepser to avoid loops
    //unset($recipients['']);
     
    $ccUnregistered = [];
    $ccRegistered = [];
     
    //for each additional recipient determine if it is a registered user or not
    foreach($recipients as $recipient => $name){
        $user = Deep::getModel('deep_admin/user')->loadByEmail($recipient);
        if($user && $user->getId()){
            //populate userassoc array
            $ccRegistered [] = $user->getUsername();
        }
        else{
            //populate unregistered user array
            $ccUnregistered [] = $recipient;
        }
    }
     
    if(count($ccRegistered)){
        //populate the userassociation, that is the cust_operation_cc_registered field
        $this->getModel()->addUserAssociations('watch', $ccRegistered);
    }
     
    if(count($ccUnregistered)) {
        //populate the custom field cust_operation_cc_unregistered, adding email addresses separated by ;
        $this->getModel()->setData('cust_operation_cc_unregistered', implode(';', $ccUnregistered));
    }
}
				
			
Note: If the user association is populated by a rule that does not make any changes to the ticket or in general to the entity to which the user association belongs, the user association will not be modified.

Email Events

Mail events are a tool closely related to Deepser mail integration.
The Mail Events configuration allows you to define:

  • When a notification must be sent
  • Which notification must be sent
  • Who are the recipients of the notification email

The emails are generated by dynamically enhancing the Template set in the event as the notification template.

Deepser contains multiple default mail events, preconfigured to work in various standard situations.

Enabling / Disabling an Email Event

Now let’s see how you can enable or disable an email event.

1 – Open the Mail Events menu, via System->Tools->Email->Events

2 – The grid containing the mail events will be loaded

Several pre-configured events are available, each event has a descriptive title, in the following form ‘Recipients of the notification – triggering event‘.

3 – Select a standard event, for example Requester – New Operation.

4 – This event sends an email notification to Requester User, at ticket creation.

To enable or disable an event, set the Status field as desired and save the event by clicking the Save or Apply buttons.

The meaning of the fields, the form of an event, is as follows:

FieldDescription
NameName of the event. Represents a descriptive field with which the events in the system will be displayed.
CodeEvent code. By convention it is a “normalization” of the Event Name, e.g.: “requester_user_new_operation”.
StatusThe status (enabled/disabled). If “Disabled” the event will not be active.
Send AttachmentsIf Yes will be sent all the attachments, of the record that triggers the event, evaluated as visible by the user with the most limited visibility among the recipients. For example, if the event concerns the notification of a new assignee in Service Operations, then the attachments of the newly updated Operations record will be sent as email attachments. Note: To learn more about configuring the visibility of attachments, see the Attachments Configuration section.
Email TemplateIt represents the template with which the emails related to the event will be sent.
ModelThe model of reference, that is the entity (ex: “DeepService – Operation” for tickets) to whose saving the email event must be executed.
Event ExpressionPHP code that identifies the condition. Through this scripting area, it is defined whether to send the email notification, based on the value of the template fields.
AScripting area in which, through PHP code, email addresses are added in the To field.
CcScripting area in which, through PHP code, email addresses are added in the Cc field.
CcnScripting area in which, through PHP code, email addresses are added in the Bcc field.
Custom CodePHP code executed after sending the email.

Custom Email Events Creation

In Deepser you can define and use custom email events in addition to the many standard events already defined in the system.

To create a new email event we can proceed in two ways: create it from scratch, or duplicate an existing one.

EMAIL EVENT CREATION

To create a new event from scratch, from the email event grid in the àEvent Email Toolsà àSystem section click on the ‘+ Create Event‘ button at the top right.

EMAIL EVENT DUPLICATION

Duplicating an event allows you to create a new event that will be the exact copy of the starting event, so that you can take full or partial advantage of its configuration.

The only differences will be the Name and the Code to which the suffixes “(copy)” and “_copy” will be added respectively.

To duplicate an already existing event, from its configuration form, click on the “Duplicate Event” button in the top right corner.

Custom Email Events Configuration

You can configure a new custom event, or modify an existing one.

Once you have filled the event form fields containing the main informations, generally contained in the “Main Data” Field Set, select the model (entity) for which to send the notification.

To enter the PHP code to configure the “Event Expression” and the notification recipients, expand the related scripting areas by clicking button with the “</> ” icon.

From the scripting areas, you can use the syntax $this->getModel() to access the instance of the selected model.

If the model is DeepActictivity – Activity, because you are creating or modifying an event for the notification when a commenti s added, with $this->getModel() you will access to the comment instance, not to the associated operation.

To access the related operation instance, use $this->getModel()->loadModelInstance().

Note: It is not possible to change the system email events configuration, in this case you need to duplicate the system email event and modify the duplicate.

EXAMPLE: CONFIGURE NOTIFICATION TO MANAGER GROUP FOR TICKETS WITH CRITICAL PRIORITY ASSIGNED TO THE FIRST LEVEL.

In this example we want to configure a notification event to send an email to “IT Managers” group if a ticket with “Critical” priority is created and assigned to the “IT First Level” group.

After defining the template and all the main event data follow these two steps.

STEP 1: “EVENT EXPRESSION” CONFIGURATION

The code in this field expresses the conditions for which a notification must be sent, in this case: “if a ticket with Critical priority is created and assigned to the IT First Level group“.

The following PHP code was used to express the condition:

				
					// Retreive the operation object
$operation = $this->getModel();
// The IT First Level group entity_id
$itFirstLevelGroupId = 10;
// Check if Operation new and Assigned Group is defined and it's exactly IT Frist Level
if($operation->isObjectNew() &&
    $operation->getAssignedGroupId() &&
    $operation->getAssignedGroupId() == $itFirstLevelGroupId){
    // "Critical" list value key
    $criticalPriorityId = 1;
    // If Operation has Critical priority then send the email notification
    if($operation->getPriorityId() == $criticalPriorityId){
        return true;
    }
}
return false;
				
			

STEP 2: RECIPIENTS CONFIGURATION

To, Cc, Bcc fils are used to define to whom the notification should be sent, in this case: “to the IT Managers group“.

To set the recipients of the notification, the following PHP code has been inserted in the ‘To‘ field.

				
					// The IT Managers group entity_id
$itManagerGroupId = 28;
// Load the IT Managers group object instance
$itManagerGroup = Deep::getModel('deep_group/group')->load($itManagerGroupId);
// Set message locale
$this->changeLanguage('en_US');
// If IT Managers group has its own email address (ex: mailing list)
if ($itManagerGroup->getEmail()) {
    // Send email to its email address
    $this->addTo($itManagerGroup->getEmail());
}
// Else send email to every user of the group
else {
    // Load all users in IT Managers group
    $managers = $itManagerGroup->loadUsers();
    // Iterate over the collection and set the email address of each manager as recipient
    foreach ($managers as $manager){
        $this->addTo($manager->getEmail());
    }
}
				
			

EXAMPLE 2: CONFIGURATION FOR SENDING NOTIFICATION TO CC INDICATED IN THE TICKET

In this example we want to modify the configuration of a notification event to the Requester User, to send the email by adding in Cc also the additional recipients indicated through a custom field in the operation.

Notification will be sent if the comment is visible to end users.

STEP 1: CREATE ADDITIONAL RECIPIENTS CUSTOM FIELD

Create a custom field in the DeepService – Operation model:

  • Column Name: cust_additional_recipients
  • Label: Additional Recipients
  • Column Type: Don’t create DB column
  • Element Type: Userassociation

Once you have created the custom field you need to add it to a formtemplate to start using it.

STEP 2: “CC” CONFIGURATION

In the Cc field all the users, associated to the operation through the custom field created in step1, are retreived and will be added in Cc to the notification email.

To set the additional recipients, use the following PHP code in the ‘Cc’ field.

You can configure a new custom event, or modify an existing one.

Once you have filled the event form fields containing the main informations, generally contained in the “Main Data” Field Set, select the model (entity) for which to send the notification.

To enter the PHP code to configure the “Event Expression” and the notification recipients, expand the related scripting areas by clicking button with the “</> ” icon.

From the scripting areas, you can use the syntax $this->getModel() to access the instance of the selected model.

If the model is DeepActictivity – Activity, because you are creating or modifying an event for the notification when a comment is added, with $this->getModel() you will access to the comment instance, not to the associated operation.

To access the related operation instance, use $this->getModel()->loadModelInstance().

				
					//REGISTERED CC
$additionalRecipient = $this->getModel()->loadModelInstance()->loadUserAssociations();
if ($additionalRecipient && is_array($additionalRecipient) && count($additionalRecipient) > 0){
    foreach ($additionalRecipient as $ccUserType){
            foreach ($ccUserType as $ccUsername){
                $ccUser = Deep::getModel('deep_admin/user')->loadByUsername($ccUsername);
                $this->addCc($ccUser->getEmail());
            }
    }
}
				
			

Also, use the following PHP code in the ‘Cc’ field to notify unregistered CC users.

				
					//UNREGISTERED CC
$additionalUnregisteredRecipient = $this->getModel()->loadModelInstance()-> getCustOperationCcUnregistered();
if ($additionalUnregisteredRecipient){
    $additionalUnregisteredRecipientArray = explode(';',$additionalUnregisteredRecipient);
    if(is_array($additionalUnregisteredRecipientArray) && count($additionalUnregisteredRecipientArray) >0){
        foreach ($additionalUnregisteredRecipientArray as $ccUnregisterdUser){
            $this->addCc(trim($ccUnregisterdUser));
        }
    }
}
				
			

Attach Report to Email Notification

You can attach a document, generated by a report already defined in Deepser, to a notification email.

This functionality is configured within Email Events.

EXAMPLE: ATTACH WORKLOG REPORT TO OPERATION CLOSURE NOTIFICATION.

To generate a report and attach it to an email notification you need to edit ‘To’ field of the email event.

In this example the configuration of the REQUESTER – Closed Operation event will be changed.

Replace the PHP code in the field ‘To‘ with the following one.

				
					//set Requester User as recipient
$user = $this->getModel()->getRequesterUser();
if ($user && $user->getId()){
    $this->changeLanguage($user->getLocale());
    $this->addTo($user->getEmail());
}
 
$attachment = Deep::getModel('deep_attachment/attachment');
//load the report instance
$report = Deep::getModel('deep_report/report')->load(14); // id 14 = Worklog Report
//pass to the report the id of the operation
$report->setFormData(['operation_id' => $this->getModel()->getId()]);
//run the report
$reportHistory = $report->run();
//set document as attachment
$attachment->setContent($reportHistory->getContent());
//define naming template
$attachment->setFileName('Worklog Report_'. $this->getModel()->getId() . '.pdf');
//set filetype
$attachment->setFileType(Zend_Mime::TYPE_OCTETSTREAM);
//add attachment to the message
$mailAttachments = new Varien_Data_Collection();
$mailAttachments->addItem($attachment);
$this->getMailbox()->setForcedAttachments($mailAttachments);
				
			

Email Templates

An Email Template defines layout and data of an email sent by Deepser.

Each email event is associated with a template.

By clicking the Preview button, on the top right corner in the email events form, it is possible to get a preview on how the notification email will appear.

By clicking the button you will be asked for the ID of the model for which you want to compile the template.

At this point the template will be displayed.

Email Template Configuration

To define a new Template, go to the System > Tools > Email > Templates menu andclick on button “Add Mail Template” in the top right corner.

The Fields of the form have the following meaning:

FIELDMEANING
CodeUnique code for the template, useful to insert the template in other templates.
NameThe name of the template, it will be displayed in the select-boxes.
StatusIf Disabled the template cannot be used.
SubjectThe phtml code for building the email subject line. Note: it is important that the subject of the email include Prefix of the mailbox and the id of the model (ex: “TICKET#101”) so, in case of reply, the model will be updated.
BodyPhtml code to compose the body of the email.
StylesCSS styles added to the body of the email

Typically, we define a set of templates and we can inlude the templates inside other templates.

This is useful in the case of header or footer for emails. You define the header with the company logo only once and then this is included in all other templates.

One more thing to pay attention to, when setting up a new template with links to display entities in Deepser, is which area they refer to.

A service operation, for example, can be displayed:

  • In Deepser Backend then to Admin, Agent and Key-User
  • In User Portal to any registered user if he is the requester or a requester supervisor
  • In Guest Portal to anyone who has appropriate link

The Url is different for each of the three areas.

New operation notification template for Requester User

In the following example,  we are going to configure an email template.

This template will be used to notify the Requester about the creation of a new operation.

STEP 1 – TEMPLATE IDENTIFICATION FIELDS

Fill in the template identificative fields:

  • Name (ex: ‘REQUESTER – OPERATION Created’)
  • Code (ex: ’email_to_requester_operation_created’)
  • Status: Enabled

STEP 2 – CONFIGURE THE EMAIL SUBJECT LINE

In the scripting area ‘Subject‘ insert the following PHP code

				
					<!--    Double underscore method check for available translations of the string passed as parameter -->
<!--   
        $this->getPrefix() retrieve the prefix setted in current outgoing mailbox configuration
        $this->getModel() returns the current model incance in this case the service operation instance
        $this->getModel()->getId() retrive the operation ID
-->
<?php echo Deep::helper('deep_email')->__('Ticket with ID')?>
 <?php echo $this->getPrefix().$this->getModel()->getId()?>
 <?php echo Deep::helper('deep_email')->__('sent')?>
				
			

The resulting subject will be like: “Ticket with ID TICKET#101 sent”.

STEP 3 – CONFIGURE THE EMAIL BODY

In the Body scripting area enter the following PHP code

				
					<?php
//$this->getModel() returns the current service operation instance
$operation = $this->getModel();
//$operation->getRequesterUser() loads the requester user object if he is registered
$requesterUser = $operation->getRequesterUser();
//test if requester is a registered user
$requesterIsRegistered = $requesterUser && $requesterUser->getId();
//if requester is registered then use getDisplayUsername() that returns 'Firstname Lastname'
//if the requester is not a registered user use the value of the service operation field requester_username
$requesterUsername = $requesterIsRegistered ? $requesterUser->getDisplayUsername() : $operation->getRequesterUsername();
?>
 
<!-- include header template -->
<?php $this->includeTemplate("header") ?>
 
<!-- Start of Main Content -->
<tr style="">
    <td bgcolor="#FFFFFF" align="center" style="">
        <table width="100%" align="center" cellpadding="0" cellspacing="0" border="0" class="devicewidth" style="">
            <tbody style="">
            <!-- Start Spacer -->
            <tr>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="h26" height="36" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- End Spacer -->
            <tr style="">
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="mktEditable content mktEditable content" id="edit_text_1" valign="middle"
                    style="font-family:Calibri, Helvetica, sans-serif; font-size:16px; color:#505050;
                        text-align:left; line-height:25.6px; font-weight:normal; text-transform:none;">
                    <p>
                        <br>
                        <?php echo Deep::helper('deep_email')->__('Dear') . ' ' . $requesterUsername ?>,
                        <br>
                         
                        <?php $url = $operation->getPortalUrl() ?>
                        <?php echo Deep::helper('deep_email')->__('Ticket with ID')?>
                        <b style="font-weight: 700;">
                            <?php if($requesterIsRegistered):?>  
                                <a href="<?php echo $url ?>"><?php echo $operation->getId()?></a>
                            <?php else:?>
                                <?php echo $operation->getId()?>
                            <?php endif;?>  
                        </b> <?php echo Deep::helper('deep_email')->__('has been received by our support')?>
                        <br><br>
                         
                        <strong><?php echo Deep::helper('deep_email')->__('Title')?></strong>:
                        <br>
                        <!-- print the operation Title -->
                        <?php echo $operation->getTitle()?>
                        <br><br>
                         
                         
                        <strong><?php echo Deep::helper('deep_email')->__('Description')?></strong>:
                        <br>
                        <!-- print the operation Description -->
                        <?php echo $operation->getDescription()?>
                        <br>
                         
                        <!-- Requester -->
                        <strong><?php echo Deep::helper('deep_service')->__('Requester User')?></strong>:
                        <?php if($requesterIsRegistered):?>
                            <?php if($requesterUser->getAvatar()):?>
                                <br>
                                <!-- if user is regitered and has an avatar print it -->
                                <img src="<?php echo $requesterUser->getAvatarUrl() ?>" border="0"
                                    style="-ms-interpolation-mode: bicubic;" width="16" />
                               <?php endif;?>
                        <?php endif;?>
                        &nbsp;&nbsp;&nbsp;
                        <!-- print the requester username -->
                        <?php echo $requesterUsername ?>
                        <br><br>
 
                        <!-- Urgency -->
                        <?php if($operation->getUrgencyId()):?>
                        <strong><?php echo Deep::helper('deep_email')->__('Urgency')?></strong>:
                            <?php
                            //load service operation urgency list
                            $urgencyList = Deep::helper('deep_list')->loadList(
                                Deep_Service_Model_Operation::LIST_CODE_URGENCY
                                );
                            //get the corrisponding Urgency label
                            $urgencyValue = $urgencyList->getValue($operation->getUrgencyId()); ?>
                            <br>
                            <!-- print urgency label -->
                            <?php echo Deep::helper('deep_email')->__($urgencyValue->getValueLabel()); ?>
                        <?php endif;?>
                        <br><br>
                    </p>
                </td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- Start Spacer -->
            <tr>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td height="30" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- End Spacer -->
            </tbody>
        </table>
    </td>
</tr>
<!-- End of Main Content -->
 
<?php if($requesterIsRegistered):?>
    <!-- start of Button -->
    <tr style="">
        <td bgcolor="#FFFFFF" align="center" class="mktEditable" id="edit_cta_button" style="">
            <table width="100%" border="0" cellspacing="0" cellpadding="0">
                <tbody>
                <tr>
                    <td class="w22" width="41" style="font-size: 1px; line-height: 1px;">&nbsp;</td>
                    <td align="left">
                        <table class="button" cellpadding="0" cellspacing="0" border="0" align="left"
                            bgcolor="#0080ff" style="-webkit-border-radius: 4px;
                                -moz-border-radius: 4px; border-radius: 4px;">
                            <tbody>
                            <tr>
                                <td width="518" align="center" valign="middle" height="65">
                                    <span style="color: #ffffff; text-decoration: none;">
                                        <!-- set the operation link as button link -->
                                        <a class="mobButton mktNoTok" href="<?php echo $url ?>"
                                            style="font-family: Calibri, Helvetica, sans-serif;
                                                font-size: 16px; color: #ffffff; display: block; height: 65px;
                                                    mso-line-height-rule: exactly; line-height: 65px;
                                                        font-weight: normal; text-decoration: none;
                                                            text-align: center!important;"
                                                                target="_blank" title="Link al ticket">
                                            <?php echo Deep::helper('deep_email')->__('Go to the Ticket')?>
                                        </a>
                                    </span>
                                </td>
                            </tr>
                            </tbody>
                        </table>
                    </td>
                    <td class="w22" width="41" style="font-size: 1px; line-height: 1px;">&nbsp;</td>
                </tr>
                </tbody>
            </table>
        </td>
    </tr>
    <!-- end of Button -->
<?php endif;?>
 
<!-- include footer template -->
<?php $this->includeTemplate("footer") ?>
				
			

The email notification body will look like the image below.

New or Updated comment notification template for Requester

In the following example, we are going to configure an email template to notify a user that a comment has been added or updated where he is  the Requester.

STEP 1 – TEMPLATE IDENTIFICATION FIELDS

As a first step, fill in the template identificative fields:

  • Name (es: ‘REQUESTER – Comment Created or Updated ’)
  • Code (es: ‘operation_comment_created_updated_requester’)
  • Status: Enabled

STEP 2 – CONFIGURE THE EMAIL SUBJECT LINE

In the scripting area ‘Subject‘ insert the following PHP code

				
					<!--
    $this->getModel() returns the current model incance in this case the activity instance
    $this->getModel()->isObjectNew() returns true if object is new
    if object is new print "New Comment" else Comment Updated
    __ method (double underscore) check for available translations of the string passed as parameter
-->
<?php if ($this->getModel()->isObjectNew()) : ?>
    <?php echo Deep::helper('deep_email')->__('New Comment')?>
<?php else: ?>
    <?php echo Deep::helper('deep_email')->__('Comment Updated')?>
<?php endif; ?>
 <?php echo Deep::helper('deep_email')->__('for Ticket ID')?>
<!--   
    $this->getPrefix() retrieve the prefix setted in current outgoing mailbox configuration
    $this->getModel()->getModelId() retrive the main model ID to which the activity is associated
        in this case the operation ID
-->
 <?php echo $this->getPrefix() ?><?php echo $this->getModel()->getModelId() ?>
				
			

The resulting subject will look like: “New Comment for Ticket ID TICKET#101” or “Comment Updated for Ticket ID TICKET#”.

STEP 3 – CONFIGURE THE EMAIL BODY

In the Body scripting area enter the following PHP code

				
					<?php
//$this->getModel() returns the main model oject instance, in this case Activity
$activity = $this->getModel();
//retreive user who created comment
$createdByUser = $activity->getCreatedBy() ?
    Deep::getModel('deep_admin/user')->loadByUsername($activity->getCreatedBy()) : null;
//determine createdby user display username
$createdByDisplayUsername = $createdByUser && $createdByUser->getId() ?
    $createdByUser->getDisplayUsername() : $activity->getCreatedBy();
//$activity->loadModelInstance() returns main model instance in this case operation object instance
$operation = $activity->loadModelInstance();
//getAssignedUser() returns assigned user object instance
$assignedUser = $operation ? $operation->getAssignedUser() : null;
//getDisplayUsername() returns "First Lastname" string
$assignedUsername = $assignedUser && $assignedUser->getId() ? $assignedUser->getDisplayUsername() : null;
//$operation->getRequesterUser() loads the requester user object if he is registered
$requesterUser = $operation ? $operation->getRequesterUser() : null;
//test if requester is a registered user
$requesterIsRegistered = $requesterUser && $requesterUser->getId();
//if requester is registered then use getDisplayUsername() that returns 'Firstname Lastname'
//if the requester is not a registered user use the value of the service operation field requester_username
$requesterUsername = $requesterIsRegistered ? $requesterUser->getDisplayUsername() : $operation->getRequesterUsername();
?>
 
<!-- include header template -->
<?php $this->includeTemplate("header") ?>
<!-- Start of Main Content -->
<tr style="">
    <td bgcolor="#FFFFFF" align="center" style="">
        <table width="100%" align="center" cellpadding="0" cellspacing="0" border="0" class="devicewidth"
            style="">
            <tbody style="">
            <!-- Start Spacer -->
            <tr>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="h26" height="36" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- End Spacer -->
            <tr style="">
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="mktEditable content mktEditable content" id="edit_text_1" valign="middle"
                    style="font-family:Calibri, Helvetica, sans-serif; font-size:16px; color:#505050;
                    text-align:left; line-height:25.6px; font-weight:normal; text-transform:none;">
                    <p>
                        <br>
                        <?php echo Deep::helper('deep_email')->__('Dear') .' ' . $requesterUsername ?>,
                        <br>
 
                        <?php echo Deep::helper('deep_email')->__('A Comment has been') .' ' ?>
                        <b>
                        <?php if ($activity->isObjectNew()) : ?>
                            <?php echo Deep::helper('deep_email')->__('created') . ' '?>
                        <?php else: ?>
                            <?php echo Deep::helper('deep_email')->__('updated') . ' '?>
                        <?php endif; ?>
                        </b>
                        <?php echo Deep::helper('deep_email')->__('for Ticket ID') ?>:
                        <b style="font-weight: 700;">
                            <?php if($requesterIsRegistered):?>
                                <?php $url = $operation->getPortalUrl() ?>
                                <a href="<?php echo $url ?>">
                                    <?php echo $operation->getId()?>
                                </a>
                            <?php else:?>
                                <?php echo $operation->getId()?>
                            <?php endif;?>
                        </b>
                        <br><br>
 
                        <!-- Ticket Title -->
                        <strong><?php echo Deep::helper('deep_email')->__('Ticket Title')?></strong>:
                        <br>
                        <!-- print the operation Title -->
                        <?php echo $operation->getTitle()?>
                        <br><br><br>
 
                        <!-- Activity Description -->
                        <strong><?php echo Deep::helper('deep_email')->__('Comment')?></strong>:
                        <!-- print the activtity Description -->
                        <br><?php echo $activity->getDescription()?>
                        <br>
 
                        <!-- Created by -->
                        <strong><?php echo Deep::helper('deep_service')
                            ->__('User who created the Comment')?></strong>:
                        <?php if($createdByUser && $createdByUser->getId()):?>
                       <?php if($createdByUser->getAvatar()):?>
                           <br>
                           <!-- if created by user is regitered and has an avatar print it -->
                           <img src="<?php echo $createdByUser->getAvatarUrl() ?>" border="0"
                               style="-ms-interpolation-mode: bicubic;" width="16" />
                            <?php endif;?>
                        <?php endif;?>
                        <!-- print created by username or displayusername -->
                        &nbsp;&nbsp;&nbsp;<?php echo $createdByDisplayUsername ?>
                        <br><br>
                    </p>
                </td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- Start Spacer -->
            <tr>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td height="30" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- End Spacer -->
            </tbody>
        </table>
    </td>
</tr>
<!-- End of Main Content -->
 
<?php if($requesterIsRegistered):?>
<!-- start of Button -->
<tr style="">
    <td bgcolor="#FFFFFF" align="center" class="mktEditable" id="edit_cta_button" style="">
        <table width="100%" border="0" cellspacing="0" cellpadding="0">
            <tbody>
            <tr>
                <td class="w22" width="41" style="font-size: 1px; line-height: 1px;">&nbsp;</td>
                <td align="left">
                    <table class="button" cellpadding="0" cellspacing="0" border="0" align="left"
                        bgcolor="#0080ff" style="-webkit-border-radius: 4px; -moz-border-radius: 4px;
                        border-radius: 4px;">
                        <tbody>
                        <tr>
                            <td width="518" align="center" valign="middle" height="65">
                                <span style="color: #ffffff; text-decoration: none;">
                                    <!-- set the operation link as button link -->
                                    <a class="mobButton mktNoTok" href="<?php echo $url ?>"
                                        style="font-family: Calibri, Helvetica, sans-serif; font-size: 16px;
                                        color: #ffffff; display: block; height: 65px;
                                        mso-line-height-rule: exactly; line-height: 65px;
                                        font-weight: normal; text-decoration: none;
                                        text-align: center!important;" target="_blank"
                                        title="Link to the ticket">
                                        <?php echo Deep::helper('deep_email')->__('Go to the Ticket')?>
                                    </a>
                        </span>
                            </td>
                        </tr>
                        </tbody>
                    </table>
                   </td>
                <td class="w22" width="41" style="font-size: 1px; line-height: 1px;">&nbsp;</td>
            </tr>
            </tbody>
        </table>
    </td>
</tr>
<!-- end of Button -->
<?php endif;?>
 
<!-- include footer template -->
<?php $this->includeTemplate("footer") ?>
				
			

The notification email body will look like the image below.

Email Webclient

Deepser has an integrated email webclient that allows users to send and manage emails directly from within the platform, facilitating communication and centralized management of company information.

EMAIL WEBCLIENT CONFIGURATION

First of all, to activate the possibility of sending via email webclient it is necessary to configure an outgoing mailbox.

Once done, it will be necessary to enable the possibility of using the mailbox for sending via email webclient.

In particular, from the “System Data” section it will be possible to configure the “Webclient Group” and “Webclient Model Alias” fields:

Both fields must always be valued so that the mailbox can be used to send emails.

Specifically:

FIELD

DESCRIPTION

Webclient Group

With this field you can enable using of the email webclient to a specific group (or to all groups).

Webclient Model Alias

With this field you can enable using of the email webclient into a specific model.

EMAIL WEBCLIENT USING FROM MODEL

The use of the email webclient, as can be guessed from the type of configuration, can therefore be used within a single model (based on the configuration of the mailboxes).

Specifically, there must be an “Emailwriter” type field within the template.

By doing so, it will be possible to invoke the email webclient to send an email directly from within a record. Below is an example of an “Emailwriter” field on the Operations template:

By clicking on the button in question, the webclient email screen will open:

Through this screen it will then be possible to compose the email and send it by clicking on the “Send” button at the top right of the screen.

Below are the details of the fields present and their use:

FIELD

DESCRIPTION

From

In this field, you can select the mailbox you want to use.

In this case you can select only the mailboxes configured to be used with email webclient.

Display Name

This field is pre-populated according to the selected mailbox. However, it can be modified to use a different display name for the email you are sending.

To

email recipient field through which you can select users or groups already registered on Deepser or enter new email addresses.

Cc

recipient field in copy of the email through which it is possible to select users or groups already registered on Deepser or enter new email addresses.

Bcc

Recipient field in blind copy of the email through which it is possible to select users or groups already registered on Deepser or enter new email addresses.

Subject

Subject of the email

Body Html

Message body

Attachments

Attachments

Create Comments

A field that, if set to “yes”, allows you to upload the email as a comment in the record to which it belongs.

Once sent, in this case, the email will be linked to the same record from which it was sent via webclient email:

GENERAL USING OF EMAIL WEBCLIENT

By clicking on the “@” icon at the top right of the Deepser screen, you can access a sub-menu that allows you to send emails or view emails sent via email webclient.

By clicking on “Write”, you will see the same email sending screen presented previously:

By accessing instead through “List” you will have the complete list of all the emails sent through this mode.

Now, a brief explanation of the buttons displayed in the grid (Webclient Messages) of sent emails:

  1. Allows you to view the email.
  2. The Ingoing Email icon box.
  3. The Outgoing Email icon box.
  4. Message not sent icon.
  5. Allows you to resend the ermail.
  6. Reply to the email.
  7. Answer to everyone.
  8.  Forward

Escalation

Escalation rules in Deepser are an important tool in Deepser’s entities management flow that allow you to perform time-based actions, e.g. modify the status, send an email or create/edit external entities based on a metric.

Escalation rule levels

In Deepser, all entities that can be processed by escalation rules have a “Level” attribute that serves as a filter to indicate which escalation rules should be evaluated on that entity.

Escalation rules process only entities whose level is equal to the “Level” attribute set in the rule itself or lower, after their execution they set the “Level” attribute of the processed entity to the  value indicated in the “Next Level” field of the rule.  

This mechanism allows you to make a skimming on the rules that will have to be evaluated for each entity, allowing you to define rules that must be evaluated only once for each entity of the selected type.

RULES THAT RUN ONLY 1 TIME PER ENTITY

To configure an escalation rule to run only once, it will be sufficient to configure the “Level” field of the escalation rules to the desired level (by default 0) and the  “Next Level” field of the rule to a value  higher than that of the  “Level” field for example to 1 in the case of default.

RULES THAT RUN MULTIPLE TIMES PER ENTITY

To make sure  that an escalation rule is executed potentially several times on the same entity, it will be sufficient to set the “Level” field and the “Next Level” field to the same value.

This will cause the rule to evaluate that ticket potentially several times  (at  most 1 per execution of the rule itself), if the “Level” of those entities were changed by  other rules, the behavior of the rule that we are configuring may not be what was expected.

For this reason, the advice we give is always to evaluate the rules as a whole to understand if one or more rules can conflict  (intentionally or not).

COMPETITION FROM ESCALATION RULES

Suppose the existence of 2 escalation rules: “A” and “B”, the “A” rule takes charge of all tickets that have not been assigned  for  more than two hours and sends an email notification  (the implementation of these types of  rules will be covered in subsequent lessons), setting the “Level” field of the processed entity  to 0 from 0.

Rule B instead takes charge of all tickets that have not been assigned for more than 4 hours and sends an email also setting the priority to “Critical” and changing the level of the entity to 1.

In this case, if a ticket’s  processed by rule “B”,  which includes more general conditions, it is intended not to be processed by rule A.

In general, however, it is necessary to pay attention to the escalation rules as a whole.

Configuring Escalation Rules

To configure a new Escalation rule in Deepser You will need to go to the System -> Service Configuration -> Escalation Rule menu.

Here, you will need to click on the “Add Rule” button.

Now the following screen will open:

Below are the fields and their meaning:

FieldDescription
NameName of the escalation rule
Model AliasModel on which it will apply
Email EventAssociated email event that will be launched if the conditions of the rule are true
LevelLevel, this field indicates what is the level of tickets that will have to be processed, by default it is 0 for all tickets
Next LevelThe new level that the ticket will have after being processed by the rule
Cron ExpressionExpression Cron, indicates how often this rule will be processed.
StatusStatus of the rule, if “Enabled” the rule will be evaluated otherwise no.

Note that the conditions to be specified for the rule will appear only after the rule has been saved at least once.

At this point, click on “Save” or “Apply” to save the rule.

At the end, the following screen will appear:

The new fields that will appear are the following:

FieldDescription
Escalate all Records with following values (Main Filter)This query builder will be used to filter the tickets that will have to be processed In order to be evaluated , tickets must comply with the conditions of the query builder
Expression Input (Script)This script field will be used to filter tickets that will have to be processed. In order to be processed, tickets must comply with the conditions of the script field (must return true).
Escalate all Records with following Timer values (applied after the Main Filter)This query builder will be used to filter tickets that will have to be processed. In order to be processed, tickets must comply with the conditions of the query builder, in addition in this case the SLA metrics will also be evaluated as parameters of the query builder.
Expression Timer (Script)This script field will be used to filter the tickets that will have to be processed . In order to be evaluated tickets must comply with the conditions of the script field in addition in this case the metrics of the SLA will be evaluated as parameters of the query builder.
Set Records values toThis query builder is used to set the values  that have to be modified in the processed record.
Expression Output (Script)This scripting field is used to set the values that have to be modified in the processed record.

As a last step, after filling in the desired fields, you will need to click on the “Save” or “Apply” button to save the rule.

Configure an escalation rule that modifies entity.

Suppose you want to configure an escalation rule that gives high priority to all tickets whose requesting company is “Acme International”.

To do this, you will need to go to the System -> Service Configuration -> Escalation Rule menu.

Here, you will need to click on the “Add Rule” button.

Now the following screen will open:

At this point, we configure the “Name” field as “High Priority Acme International”.

We set the field “Model Alias” to “DeepService – Operation”.

Now, we configure the Level to zero and Next Level to1 fields, that is, this rule will process all tickets in zero state only once.

At this moment, we set the field “Cron Expression”: every 5 minutes using the drop-down menu located under the field itself.

As the last step of this first phase, click on “Save” or “Apply” to save the rule.

CONFIGURING QUERY BUILDERS

Now configure in the newly created rule the query builder “Escalate all Records with following values (Main Filter)” like this:

Now, let’s set in the newly created rule the query builder “Set Records values to” like this:

Finally, we can click on “Save” or “Apply”.

Escalation rule that sends an email notification

In Deepser, Escalation rules can trigger email notifications. This allows you to use escalation rules to eliminate alerts   when specific events occur. In the following example, we are going to create an escalation rule that will notify the user  in case  the requesting company is Acme International. In this example, we will also use the escalation rule created  in the previous example.

E-MAIL TEMPLATE CREATION

In order to send the email notification to the assignee user, it will be necessary to create an email event with its associated mail template that will be used by Deepser to send the email from the escalation rule. To create a custom, you will need to go to the System -> Tools -> Email -> Template menu. Then you will need to click on the”Add  Mail Template” button. In the screen that will open you will need to define a name for the template, to do this, simply enter the desired name in the “Name” field. Next we will define a code for the template, filling in the “Code” field. At this point, it will be possible to insert in the”Subject”section the php code that will compose the subject of the email. You can use the following code as a reference to compose the subject of the email:

				
					<?php echo Deep::helper('deep_email')->__('DEEPSER – New ticket from Acme International')?>
				
			

Now, it will be possible to insert in the “Body” section, which will represent the content of the message, the PHP / HTML code that will be used to generate the body of the mail.

You can use the following code as a reference when creating the body:

				
					<?php

$requesterUser = $this->getModel()->getRequesterUser();

$assignedUser = $this->getModel()->getAssignedUser();

?>

<?php $this->includeTemplate(“header”) ?>

<!– Start of Main Content –>

<tr style=””>

    <td bgcolor=”#FFFFFF” align=”center” style=””>

        <table width=”100%” align=”center” cellpadding=”0″ cellspacing=”0″ bor-der=”0″ class=”devicewidth” style=””>

            <tbody style=””>

            <!– Start Spacer –>

            <tr>

                <td class=”w22″ width=”41″ style=”font-size:1px; line-height:1px;”>&nbsp;</td>

                <td class=”h26″ height=”36″ style=”font-size:1px; line-height:1px;”>&nbsp;</td>

                <td class=”w22″ width=”41″ style=”font-size:1px; line-height:1px;”>&nbsp;</td>

            </tr>

            <!– End Spacer –>

            <tr style=””>

                <td class=”w22″ width=”41″ style=”font-size:1px; line-height:1px;”>&nbsp;</td>

                <td class=”mktEditable content mktEditable content” id=”edit_text_1″ valign=”middle” style=”font-family:Calibri, Helvetica, sans-serif; font-size:16px; color:#505050; text-align:left; line-height:25.6px; font-weight:normal; text-transform:none;”>

                    <p>

                        <br>

                        <?php echo Deep::helper(‘deep_email’)->__(‘Dear %s’, $this->getModel()->getAssignedUser()->getDisplayUsername())?>,<br>

                        <?php $url = $this->getModel()->getAssignedUser()->isUser() ? $this->getModel()->getPortalUrl() : $this->getModel()->getUrl(); ?>

                        <?php echo Deep::helper(‘deep_email’)->__(‘You have Re-cived a new ticket from Acme International’)?> <b style=”font-weight: 700;”><a href=”<?php echo $url ?>”><?php echo $this->getModel()->getId()?></a></b>

                        <br>

                        <br>

                        <strong><?php echo Deep::helper(‘deep_email’)->__(‘Title’)?></strong>:

                        <br><?php echo $this->getModel()->getTitle()?><br><br>

                        <strong><?php echo Deep::helper(‘deep_email’)->__(‘Description’)?></strong>:

                        <br><?php echo $this->getModel()->getDescription()?><br>

                        <!– Status –>

                        <?php if($this->getModel()->getStatus()):?>

                        <strong><?php echo Deep::helper(‘deep_email’)->__(‘Status’)?></strong>:

                            <?php

                            $statusList = Deep::helper(‘deep_list’)->loadList(Deep_Service_Model_Operation::LIST_CODE_STATUS);

                            $statusValue = $statusList->getValue($this->getModel()->getStatus());

                            ?>

                            <br><?php echo Deep::helper(‘deep_email’)->__($statusValue->getValueLabel()); ?><br><br>

                        <?php endif;?>

                        <!– Requester –>

                        <?php if($requesterUser && $requesterUser->getId()):?>

                            <strong><?php echo Deep::helper(‘deep_service’)->__(‘Requester User’)?></strong>:

                            <?php if($this->getModel()->getRequesterUser()->getAvatar()):?>

                            <br><img src=”<?php echo $this->getModel()->getRequesterUser()->getAvatarUrl() ?>” border=”0″ style=”-ms-interpolation-mode: bicubic;” width=”16″ />

                            <?php endif;?>

                            &nbsp;&nbsp;&nbsp;<?php echo $this->getModel()->getRequesterUser()->getDisplayUsername() ?><br><br>

                        <?php endif;?>

                        <!– Assigned –>

                        <?php if($assignedUser && $assignedUser->getId()):?>

                        <strong><?php echo Deep::helper(‘deep_service’)->__(‘Assigned User’)?></strong>:

                            <?php if($this->getModel()->getAssignedUser()->getAvatar()):?>

                            <br><img src=”<?php echo $this->getModel()->getAssignedUser()->getAvatarUrl() ?>” border=”0″ style=”-ms-interpolation-mode: bicubic;” width=”16″ />

                            <?php endif;?>

                            &nbsp;&nbsp;&nbsp;<?php echo $this->getModel()->getAssignedUser()->getDisplayUsername() ?><br><br>

                        <?php endif;?>

                        <!– Urgency –>

                        <?php if($this->getModel()->getUrgencyId()):?>

                        <strong><?php echo Deep::helper(‘deep_email’)->__(‘Urgency’)?></strong>:

                            <?php

                            $urgencyList = Deep::helper(‘deep_list’)->loadList(Deep_Service_Model_Operation::LIST_CODE_URGENCY);

                            $urgencyValue = $urgencyList->getValue($this->getModel()->getUrgencyId());

                            ?>

                            <br><?php echo Deep::helper(‘deep_email’)->__($urgencyValue->getValueLabel()); ?><br><br>

                        <?php endif;?>

                        <!– Priority –>

                        <?php if($this->getModel()->getPriorityId()):?>

                        <strong><?php echo Deep::helper(‘deep_email’)->__(‘Priority’)?></strong>:

                            <?php

                            $priorityList = Deep::helper(‘deep_list’)->loadList(Deep_Service_Model_Operation::LIST_CODE_PRIORITY);

                            $priorityValue = $priorityList->getValue($this->getModel()->getPriorityId());

                            ?>

                            <br><?php echo Deep::helper(‘deep_email’)->__($priorityValue->getValueLabel()); ?><br><br>

                        <?php endif;?>

                        <!– Solution –>

                        <?php if($this->getModel()->getSolution()):?>

                        <strong><?php echo Deep::helper(‘deep_email’)->__(‘Solution’)?></strong>:

                        <br><?php echo $this->getModel()->getSolution()?>

                        <br>

                        <?php endif;?>

                    </p>

                </td>

                <td class=”w22″ width=”41″ style=”font-size:1px; line-height:1px;”>&nbsp;</td>

            </tr>

            <!– Start Spacer –>

            <tr>

                <td class=”w22″ width=”41″ style=”font-size:1px; line-height:1px;”>&nbsp;</td>

                <td height=”30″ style=”font-size:1px; line-height:1px;”>&nbsp;</td>

                <td class=”w22″ width=”41″ style=”font-size:1px; line-height:1px;”>&nbsp;</td>

            </tr>

            <!– End Spacer –>

            </tbody>

        </table>

    </td>

</tr>

<!– End of Main Content –>

<!– End of Main Content –>

<?php $url = $this->getModel()->getUrlByUser($assignedUser); ?>

<!– start of Button –>

<tr style=””>

    <td bgcolor=”#FFFFFF” align=”center” class=”mktEditable” id=”edit_cta_button” style=””>

        <table width=”100%” border=”0″ cellspacing=”0″ cellpadding=”0″>

            <tbody>

            <tr>

                <td class=”w22″ width=”41″ style=”font-size: 1px; line-height: 1px;”>&nbsp;</td>

                <td align=”left”>

                    <table class=”button” cellpadding=”0″ cellspacing=”0″ bor-der=”0″ align=”left” bgcolor=”#0080ff” style=”-webkit-border-radius: 4px; -moz-border-radius: 4px; border-radius: 4px;”>

                        <tbody>

                        <tr>

                            <td width=”518″ align=”center” valign=”middle” height=”65″>

                                <span style=”color: #ffffff; text-decoration: none;”>

                                        <a class=”mobButton mktNoTok” href=”<?php echo $url ?>” style=”font-family: Calibri, Helvetica, sans-serif; font-size: 16px; color: #ffffff; display: block; height: 65px; mso-line-height-rule: exactly; line-height: 65px; font-weight: normal; text-decoration: none; text-align: center!important;” target=”_blank” title=”Link al ticket”>

                                            <?php echo Deep::helper(‘deep_email’)->__(‘Go to the Ticket’)?>

                                        </a>

                                </span>

                            </td>

                        </tr>

                        </tbody>

                    </table> </td>

                <td class=”w22″ width=”41″ style=”font-size: 1px; line-height: 1px;”>&nbsp;</td>

            </tr>

            </tbody>

        </table>

    </td>

</tr>

<!– end of Button –>

<?php $this->includeTemplate(“footer”) ?>
				
			

And click on the “Save” or”Apply”button

EMAIL EVENT CREATION

To create a custom mail event you will need to go to the System -> Tools -> Email -> Event menu. At this point you will need to click on the”Add  Event” button. At this moment, it will be necessary to give a name to the event by filling in the “Name” field. We define Whether to send attachments by changing the value of the field”Send  Attachments” to “No”. Now in the “Email Template” field we select the template created in the previous point of this guide. In the “Event Trigger” section, select “DeepService – Operation” in the “Model” field In the “Event Expression”entry. We insert the following code:

				
					// if the Company is Acme International
if($this->getModel()->getData("requester_company_id") == Deep::getModel("deep_company/company")->load("ACME International",'name')->getId() ){
    if ($this->getModel()->getData('escalation_rule')){
         return true;
    }
}
return false;
				
			

In the “To” section We insert the following code:

				
					$user = $this->getModel()->getAssignedUser();
if ($user && $user->getId()){
    $this->changeLanguage($user->getLocale());
    $this->addTo($user->getEmail());
}
				
			

At this point, we can go to click the “Save” or “Apply” button Now the event will have been saved

ASSIGNING THE MAIL EVENT TO THE ESCALATION RULE

To assign the mail event to the escalation rule you will need to go to the menu: System ->  Service  Configuration. Here you will need to go to the previously created rule or any escalation rule you want to change. In the Escalation Rule screen you will need to select the Created event from the drop-down menu that will appear by clicking the “Email Event” field. At this point you will need to click the “Save” or”Apply” button.

EXAMPLE: SENDING EMAIL TO THE OPERATOR WHEN THE NUMBER OF HOURS IS LESS THAN 4

In this example, suppose you want to email the administrator when the number of hours remaining in a contract line is less than 4

E-MAIL TEMPLATE CREATION

In order to send the email notification to the administrator, it will be necessary to create an email event with its associated mail template that will be used by Deepser to send the email from the escalation rule. To create a custom mail event, you will need to go to the System -> Tools -> Email -> Template menu. Then you will need to click on the”Add  Mail Template” button. In the screen that will open you will need to define a name for the template, to do this, simply enter the desired name in the “Name” field. Next we will define a code for the template, filling in the “Code” field. At this point, it will be possible to insert in the”Subject”section the php code that will compose the subject of the email. You can use the following code as a reference to compose the subject of the email:

				
					<?php $line = $this->getModel()?>
The contract line <?php echo $line->getLineNumber() . ' - ' . $line->getName()?> of the contract <?php echo $line->loadContract()->getContractNumber() . ' - ' . $line->loadContract()->getName()?> is going low
				
			

Now it will be possible to insert in the “Body” section, which will represent the content of the message, the PHP / HTML code that will be used to generate the body of the mail. You can use the following code as a reference when creating the body:

				
					<?php $this->includeTemplate("header") ?>
<style>
    .table{
        width: 100%;
        margin-left:auto;
        margin-right: auto;
    }
    .tr,.td{
        width: 100%;text-align: center;
        vertical-align: middle;
    }
    .cust-container{
        display: flex;
        justify-content: center;
        margin-left: auto;
        margin-right: auto;
    }
      
</style>
<!-- Start of Main Content -->
<tr style="">
    <td bgcolor="#FFFFFF" align="center" style="">
        <table width="100%" align="center" cellpadding="0" cellspacing="0" border="0" class="devicewidth" style="">
            <tbody style="">
            <!-- Start Spacer -->
            <tr>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="h26" height="36" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- End Spacer -->
            <tr>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="mktEditable content mktEditable content" id="edit_text_1" valign="middle" style="font-family:Calibri, Helvetica, sans-serif; font-size:16px; color:#505050; text-align:left; line-height:25.6px; font-weight:normal; text-transform:none;">
                    <p>
                        <br>
                            <div class="cust-container">
                                <?php $residuo = sprintf("%02d:%02d", floor($line->getRemainingTime()/3600), floor(($line->getRemainingTime()/60) %60))?>
                                The Contract Line &nbsp;<b><?php echo $line->getLineNumber() . ' - ' . $line->getName()?> </b> &nbsp;<?php echo " is going low ({$residuo} Hours remaning ) ";?>
                             </div>
                        <br>
                        <br>
                       
                        <table class="table">
                            <tr class="tr">
                                <td>
                                    <strong><?php echo Deep::helper('deep_email')->__('Total Time')?></strong>:
                                    <br><?php echo sprintf("%02d:%02d", floor($line->getTotalTime()/3600), floor(($line->getTotalTime()/60) %60))?><br><br>
                                </td>
                                <td>
                                      <strong><?php echo Deep::helper('deep_email')->__('Remaining Time')?></strong>:
                                      <br><?php echo sprintf("%02d:%02d", floor($line->getRemainingTime()/3600), floor(($line->getRemainingTime()/60) %60))?><br><br>
                                </td>
                            </tr>
                            <tr class="tr">
                                <td>
                                      <strong><?php echo Deep::helper('deep_email')->__('Name')?></strong>:
                                      <br><?php echo $contract->getName()?><br><br>
                                </td>
                                <td>
                                      
                                     <strong><?php echo Deep::helper('deep_email')->__('Customer Company')?></strong>:
                                     <br><?php echo $company && $company->getId() ? $company->getName() : ''?><br><br>
                                </td>
                            </tr>
                        </table>
                        
                        
                      
                        
                      
                      
                    </p>
                </td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- Start Spacer -->
            <tr>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td height="30" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- End Spacer -->
            </tbody>
        </table>
    </td>
</tr>
<!-- End of Main Content -->
<?php $this->includeTemplate("footer") ?>
				
			

And click on the “Save” or”Apply” button.

EMAIL EVENT CREATION

To create a custom mail event, you will need to go to the System -> Tools -> Email -> Event menu. At this point, you will need to click on the”Add  Event” button. At this point, it will be necessary to give a name to the event by filling in the “Name” field. We define Whether to send attachments by changing the value of the field”Send  Attachments” to “No”. Now in the “Email Template” field, we select the template created in the previous point of this guide. In the “Event Trigger” section, select “DeepService – Operation”in the “Model” field In the “Event Expression”entry. We insert the following code:

				
					if ($this->getModel()->getData('escalation_rule')){
        return true;
}
return false;
				
			

In the “To” section We insert the following code:

				
					$adminUserToNotify = 'admin';
$admin = Deep::getModel('deep_admin/user')->loadByUsername($adminUserToNotify);
if($admin && $admin->getId()){
    $adminEmail = $admin->getEmail();
    if($adminEmail){
        $this->changeLanguage($admin->getLocale());
        $this->addTo($adminEmail);
    }
}
				
			

At this point, we can go to click the “Save” or”Apply” button Now the event will have been saved

ASSIGNING THE MAIL EVENT TO THE ESCALATION RULE

To assign the mail event to the escalation rule you will need to go to the menu: System -> Service Configuration. Here you will need to go to the previously created rule or any escalation rule you want to change. In the Escalation Rule screen, you will need to select the Created event from the drop-down menu that will appear by clicking the “Email Event” field. At this point, We are going to configure the “Level” field to 0 and the “Next Level” field to 1. Since we do not want to receive the notification every time the rule runs, but only the first time. Finally we are going to configure the field “Cron  Expression”at 5 minutes using the drop-down menu located below the field itself. In the “Escalate all Records with following values (Main Filter)” field.At this point, you will need to click the “Save” or “Apply” button.

Create an escalation rule that is based on a metric

In Deepser, you can configure an escalation rule based on a metric.

This allows you to perform actions in Deepser for example when a ticket is not assigned after a certain time from its creation.

Configuring the rule

For this example, suppose we have a “Time to Respond” metric already configured, it will have as a start condition that the ticket status is “New”, and as a Stop condition that the state is any other state that is not “New”.

To configure a new escalation rule, you will need to go to the System -> Service Configuration -> Escalation Rule menu.

Here you will need to click on the “Add Rule” button.

Now the following screen will open:

At this  point  we configure the “Name” field as “Set  priority high for non-assigned ticket after 1 hour”.

We set the field “Model Alias” to “DeepService – Operation”.

Now we configure the Level to zero and Next Level field to one, that is, this rule will process all the tickets in zero state and also update the Level to avoid double processing entity.

At this moment, we set the field “Cron Expression” Every 5 minutes using the drop-down menu located below the field itself.

As the last step of this first phase, click on “Save” or “Apply” to save the rule.

CONFIGURING QUERY BUILDERS

Now configure in the newly created rule the query builder “Escalate all Records with following Timer values (applied after the Main Filter)” like this:

At this point, we have to configure the query builder “Set Records values to” like this:

Finally, we can click on “Save” or “Apply”.

Configure an escalation rule that generates other entities

Suppose you want to configure an escalation rule that gives high priority to all tickets whose requesting company is “Acme International” and that adds a comment not visible to users that reports some quick contact information for the operator who will have to handle the request.

To do this you will need to go to the System -> Service Configuration -> Escalation Rule menu.

Here, you will need to click on the “Add Rule” button.

Now the following screen will open:

At this point, we configure the “Name” field as “High Priority Acme International” and load Primary Contact Information”.

We set the “Model Alias” field to “DeepService – Operation”.

Now configure the Field “Level” to 0 and Next Level to 1, that is, this rule will process all the tickets whose level is zero and then change this level to 1 so as not to reprocess the same tickets.

Please pay attention that in the case of several escalation rules active at the same time and potentially changing the level.

At this point, we set the field “Cron Expression” Every 5 minutes using the drop-down menu located below the field itself.

As the last step of this first phase, click on “Save” or “Apply” to save the rule.

CONFIGURING QUERY BUILDERS

Now configure in the newly created rule the query builder “Escalate all Records with following values (Main Filter)” like this:

Now configure in the rule just created the query builder “Set Records values to” like this:

At this point in the “Output section (Script)” we are going to insert the following code:

				
					$entityId = $this->getModelOutput()->getId();
$company = $this->getModelOutput()->loadRequesterCompany();
if($company && $company->getId()){
    $primaryContactUserName = $company->getData('primary_contact');
    $primaryContact = Deep::getModel('deep_admin/user')->loadByUsername($primaryContactUserName);
    if($primaryContact && $primaryContact->getId()){
        $primaryContactName = $primaryContact->getFirstname() . " " . $primaryContact->getLastname();
        $primaryContactEmail = $primaryContact->getEmail() ? $primaryContact->getEmail() : "" ;
        $primaryContactPhone = $primaryContact->getPhone() ? $primaryContact->getPhone() : "";
         
        $Description = nl2br("\n=================================================================\n
                                 Nome Referente: {$primaryContactName}\n
                                 Telefono Referente: {$primaryContactPhone}\n
                                 Email Referente: {$primaryContactEmail}\n
                                =================================================================\n");
         
         
        $comment =  Deep::getModel('deep_activity/activity');
        $comment->setPortalVisibility(0)
                ->setType(1)
                ->setModelId($entityId)
                ->setModelAlias("deep_service/operation")
                ->setDescription($Description)
                ->setStatus(1)
                ->save();
         
    }
}
				
			

Now we can click on “Save” or “Apply”.

Importing Data

This class is specific to importing data in Deepser. You will learn how to use Deepser’ Import Tool to create models in Deepser from Every well formatted File.

Deepser allows you to easily import entities from an external data source.

A way to do that is to configure an Import procedure from the web interface of the software.

Another way is using the API. There is a library, in a public GitHub repository also to use Deepser integration. The library is at: https://github.com/deepser/api-php

We offer also the possibility to ask for Professional Services of Deepser and have a certified Project Manager / Consultant of Deepser to implement the integration for you.

Think about those large Excel files filled with thousand of rows of data, you can automatically import their content in Deepser to manage and organize them through a user-friendly web tool, you can even schedule imports to always keep you data up to date.

Import Foundamentals

To configure a new import procedure, please go to the menu: System > Tools > Import.

In the first page after clicking on the menu, you can see a grid of all Imports already configured in your Deepser.

To see the configuration for a specific import, click on the row in the grid. Press ‘Add Import’ to create a new one.

Then we can see the Import configuration form:

The Fields have the following meaning:

FIELDMEANING
NameName of the Import.
ModelModel of the entities that are going to be imported into Deepser (Operations, CI, Companies etc.).
TypeFormat of the source file containing the records to be imported in Deepser.
Has Header (Yes/No)The first row of the file is an header. If Yes, Deepser will ignore the data of the first row of the Excel File.
Cron ExpressionIf the first row of the Excel file is a document header, it cells can be automatically recognaised as entity fields, this comes handy during the binding process
StatusIf Enabled the import will run, otherwise not.
File PathIt is used to upload the source file containing the records to be imported.
Path ExpressionIt is used to dynamically change the name of the file, containing the data to be imported. We will explain this field with an example, below in this document.
Entity – File – CodeIn this field there is the configuration of the ‘File Column – Entity Field’ binding. Entity: Model field; File: File column; Code: script to perform specific manipulations of data on the column value (e.g.: format a date, convert a value, etc.), executed during the cell evaluation.
Before RunCustom PHP code to be executed before the import procedure starts. It is used (see examples below) to pre-load data in memory, in order to avoid subsequent massive SQL queries to the DB. e.g.: Load the content of a DB table inside an Array. This action can then be used during the import, to avoid querying the database for every Excel file row.
Before RowCustom PHP code to be executed before each Excel file row is imported. It is used (see examples below) to dynamically change the values of the row imported. e.g.1: for every row imported we want to set the status as “New”. We can specify that inside this field. e.g.2: we want to load a record of the DataBase instead of importing a new record. We can load the record from the DataBase here, or read the record from the Before Run Array, representing the data on the DB Table.
After RowCustom PHP code executed after each row, as soon as every single record has been saved. It is executed multiple times after every row insert/update.
After RunCustom PHP code executed after all Excel file rows have been imported. It can be useful to perform custom tasks at the end of the import.

Import Creation

1 – At first, start by choosing a name for the import procedure and the model of the entity to be created

2 – Then select the appropriate file extension, and if it contains an header, set “Header” to yes.

2b – if the file is a .CSV, configure the appropriate delimiters and enclosures (character used to end a line)

The field “Type” defines the file format.

It can be “CSV” or “XLS”.

These are the standard formats supported by Deepser.

As you can see in the example file attached below, each row will be treated as a single record to import, each column as single Model Field:

CODENAMETYPESUBTYPESTATUSACTIVATION DATES/NNOTESOWNER COMPANYASSIGNED USER
106545Apple Iphone XIMobilesSmartphonesActive15/03/2019LFC6370742Scratches on the screenINTODEEP srl4\euler
106546Datapower 45ServersPhysical ServerActive20/12/2019LEV6267443 INTODEEP srl4\riemann
106547Dell EM5000ComputersWorkstationsActive5/04/2020LF96128119 INTODEEP srl4\riemann
106548HP Pavilion 15SComputersLaptopsActive23/04/2020L8M6200959Noise coming from cooling fanINTODEEP srl4\riemann

Table1: example of an Excel File to import devices as CMDB Cis

3 – Remember to change the status to “enabled”, then click on the Upload button under  “path label”.

4 – After the upload occurred, Deepser will recognise every field name in the document header, if present, the next step is the binding process.

Import Basic Data Binding

FIELD CONFIG: ENTITY – FILE – CODE

This field is used to perform the binding (also called “mapping”) between each column of the source import file (Excel file) and the fields of the selected model in the Database, so that deepster can populate every field of its database with the correct corrisponding value.

Entity: this column has a list of fields from the entity inside the Database of Deepser. It is the list of fields (also custom fields) present in the DB table for the Model Selected. E.g.: if you select “DeepCmdb – Ci” Model, here you will find all the fields of the CIs in the Deepser database table deep_cmdb_ci.

File: it represents the column of the Excel import file, which is read. It is selected from a select-box containg the names of columns in the File header (first row of the Excel).

Code: by clicking the button in the code column, a scripting area will open. The PHP code in this area will be executed when the value of the single column selected is evaluated and saved.

1 –  To define a new binding occurence, simply click the “+” button (light blue, below the fields list), to delete it, instead click on the red ‘minus’ button on the right side.

2 –Now you can bind each field(column name) from the source file to the corrisponding one in the Deepser entity model.

3 – Once the binding is completed, everything is set up for a basic import procedure, and you can start the process by saving and then clicking on the yellow ‘Run’button, or schedule the import to recur over time. If everything went well, a green label should state how many entities were affected.

Import Before Run

OVERVIEW

Sometimes there’s the need to import files with complex data types, or to avoid creating duplicates, etc., for all these needs the code section is essential, there are 4 main coding section, plus one for each entity field.

BEFORE RUN

The scripting area “Before Run” is were to put Custom PHP code that has to be executed before import procedure starts.

It is commonly used to retrieve records from the DataBase and to put those records inside an Array, in order to avoid multiple select queries on the DB.

Typically, data retrieved are the same model of the import. But we can use this scripting area also to pre-load related models. For example, if we are importing CMDB CI records, we could pre-load a collection of CMDB Types and CMDB Subtypes inside this scripting areas.

The collections are typically stored inside variables, that are available also inside the other scripting areas.

Attention: if you use the same name of a PHP variable, it will be overwritten.

Import Before Run Tutorial

In the following example we are retrieving devices already inside Deepser’s DataBase, to avoid duplicates when importing new records from an Excel.

We’re also retrieving Companies, Types, Subtypes and Status List Values to convert their names to corresponding IDs.

				
					/* through the static method in Deep class, a collection of CI is retrived. The collection is filtered by class_id = 2 that represents the 'Device' class*/
$deviceCollection = Deep::getResourceModel('deep_cmdb/ci_collection')->addFieldToFilter('class_id',['eq' => 2]);
/*  declaring array containing device instances */
$deviceArray = [];
/*  each element of the collection is saved in an associative array, having as key the CODE field (first column of the import file) and as value the instance of the Device. The instance is a PHP object with all the data inside the Database for the record */
foreach($deviceCollection as $device){
    $deviceArray[$device->getCustCode()] = $device;
}
 
/*  declaring an array containing type-subtype tree */
$subtypesTree = [];
/*  declaring array used for id->name type traslation */
$typeIdentity = [];
/*  retrieving CMDB Type collection through static method getResourceModel in Deep class */
$typeCollection = Deep::getResourceModel('deep_cmdb/type_collection');
/*  retrieving CMDB Subtype collection through static method getResourceModel in Deep class */
$subtypeCollection = Deep::getResourceModel('deep_cmdb/subtype_collection');
 
foreach ($typeCollection as $type){
    /*  for each type, the array tree is populated assigning the name of the type converted into uppercase    
        and a child array as a value, whose key 'id' corresponds to the type id
    es: arrayTree [typeName] ['id'] = typeId */
    $subtypesTree [strtoupper($type->getName())] = ['id' => $type->getId()];
    /*  for each type, the identity array is configured by assigning the id as key and name
    converted uppercase as value the name attribute transformed into uppercase */
    $typeIdentity[$type->getId()] = strtoupper($type->getName());
}
 
/*  for each subtype, the types in the array tree are updated by updating child array, adding the element
    that represents a subtype having as key the name of the subtype transformed into uppercase, and as 
          value the id of the subtype. eg: arrayTree [typeName] [subtypeName] = subtypeId */
foreach ($subtypeCollection as $subtype){
    $subtypesTree[$typeIdentity[$subtype->getTypeId()]] = array_merge($subtypesTree[$typeIdentity[$subtype->getTypeId()]], [strtoupper($subtype->getName()) => $subtype->getId()]);
}
/*  retrieving Company collection through static method getResourceModel in Deep class */
$companyCollection = Deep::getResourceModel('deep_company/company_collection');
$companyArray = [];
foreach($companyCollection  as $company){
    /*  for each company, the array is configured by assigning as key the company name
transformed into uppercase and company id as value */
    $companyArray [strtoupper($company->getName())] = $company->getId();
}
 
/*  Retrieving values and keys of cmdb_ci_status list
Deep::helper('deep_list')   retieving list helper which is an utility class
->loadListValues('cmdb_ci_status')  retieving list elements
->toOptionHash()    the return collection is converted in a key = label array
array_flip      wrapping keys with vakues
array_change_key_case       keys case converted to uppercase */
$statusArray = array_change_key_case(array_flip(Deep::helper('deep_list')
        ->loadListValues('cmdb_ci_status')->toOptionHash()),CASE_UPPE
				
			

Import Before Row

The PHP code in the “Before Row” scripting area will be executed before each row of the import file is evaluated field by field.

It is very important to highlight the meaning of the $model variable.

The $model reserved variable is used to populate data of the entity that will be imported.

It is a PHP Object of the same type of the Model field specified in the Import. So, for example, if the Import is related to a DeepCmdb – Ci Model, then the $model variable will contain a Deep_Cmdb_Model_Ci Object. It represents a record of the Cmdb Ci Table in the Database.

It is also very important to highlight the meaning of the $data variable.

The $data reserved variable is used to expose data of the current Excel file row.

It is a PHP Array containing the values of every column of the Excel current row.

So, in the Excel reported above (see Table1), the variable $data will contain the following value for the first row of the Excel:

$data[0] = “106545”
$data[1] = “Apple Iphone XI”
$data[2] = “Mobiles”
$data[3] = “Smartphones”
$data[4] = “Active”
$data[5] = “15/03/2019”
$data[6] = “LFC6370742”
$data[7] = “Scratches on the screen”
$data[8] = “INTODEEP srl”
$data[9] = “4\euler”

Starting from the variables described before, the Before Row is used to retrieve a model from the database starting from an alphanumeric value.

So, for example, if a record must be loaded by CODE column in the Excel (see Table1) and not for ID, in the before row you can load the record with that code, starting from the Excel and the Database of Deepser.

In this case, the original DB record, once loaded into the $model variable, can be updated with the values in the current Excel file row, instead of creating a new record for every Excel row.

Import Before Row Tutorial

In the following example the column “CODE” is checked. If it is not empty and another Device with the same code already exists, the device will be updated with data in the current row of the import file.

Without this check, a new device would be created.

				
					/*  the Excel file column with index 0 (column A) containing the CODE field is evaluated.
the $data array represents the current line of the import file and it has all
its values accessible via the Excel column index. The index starts from 0. */
$deviceCode = trim((string)$data[0]);
/*  if the column containing the attribute 'CODE' is not empty */
if($deviceCode){
    /*      if a device with same CODE already exists
    the $deviceArray array was created with key = CODE and value = instance of the device
    in 'Before Run' area */
    if(array_key_exists($deviceCode,$deviceArray)){
        /*  the instace of the device already present, with the same code, is assigned to
    the $model object
    $model object represents the current instance of the
    Deep_Cmdb CI model (specified in the Model field of the import configuration)*/
        $model = $deviceArray[$deviceCode];
    }
    /*  the class_id attribute is set by default to 2 (Device) */
    $model->setClassId(2);
}
else {
    /*  if 'CODE' is empty, the current model is set to null to avoid saving
    any empty or incomplete records */
    $model = null;
}
				
			

Import After Row

The PHP code in the “After Row” area is executed after the record in the current Excel file row has been saved into the Database.

Usually, in this area, you can set all the fields that don’t have a corresponding column in the import file, because they are calculated starting from other fields’ value.

Another use case is when you need to update the array of objects created in the “Before Run” area used to verify the uniqueness of a record. After an insert, you should add the new record to the original data collection / array created when the import starts.

Import Binding The Unique Field “Code”

The following examples refers to the code present next to each entity field

Here you can use the $value variable to get the current column’s value.

The following example shows the PHP code for binding the “CODE” field with no spaces at the beginning or at the end of the string.

This is a very important safety check for key fields and we suggest to perform this check every time you want to import a key field or a calculated key field.

				
					/*  $value contains the value of the current column in the import file, calling trim()
method (after casting as string type) to eliminate any space at the beginning or
at the end of the string */
$value = trim((string)$value);
/* after spaces were removed, the 'CODE' present in the import file is saved in the
cust_code field of the current model */
$model->setCustCode($value);
				
			

Import Binding the Type Value

The following example shows the code used to bind the “TYPE” field, assigning to the $model, the id of the Type which is specified using a name in the import file.

This example is very useful if we want to import data not with their keys, but with their alphanumeric (human readable) values.

				
					/*  $value contains the value of the current column in the import file, calling trim()
method (after casting as string type) to eliminate any space char at the beginning or
at the end of the string */
$value = trim($value);
/*  if $value isn’t null and isn’t empty */
if($value){
    /*  if the type name exists in DeepDesk. This is checked by testing if the name in the Excel file is a
    key in $subtypesTree array, created in the 'Before Run' scripting area */
    if (array_key_exists(strtoupper($value), $subtypesTree)) {
        /*  the type id is retrieved from the subtypesTree array and saved in the field
    type_id of the current model */
        $model->setTypeId($subtypesTree[strtoupper($value)]['id']);
    }
    else {
        /*  if the type name specified in the file doesn't exist in DeepDesk, then type_id
    is set to null */
        $model->setTypeId(null);
    }
}
else {
    /*  if no type name has been specified in the import file, then type_id
    is set to null */
    $model->setTypeId(null);
}
				
			

Import Binding the Dates Values

In the example below, the ACTIVATION DATE column is converted to Database format and assigned to the Activation Date model field.

				
					/*  the conversion is surrounded with a try-catch to avoid throwing exceptions */
try{
    /*  a DateTime object is created from the format used in the import file */
    $date = DateTime::createFromFormat('d/m/Y', $value);
    /*  the field 'cust_activation_date' is set with the created date formatted in the Database
    accepted format */
    $model->setCustActivationDate($date->format('Y-m-d'));
}
catch(Exception $exxx){
    /*  any exception is printed to the import_device.log log file, if the file doesn't exist
    it will be created */
    Deep::log($exxx,null,'import_device.log');
    Deep::log('value: '.$value, null, 'import_device.log');
    Deep::log('date: '.$date, null, 'import_device.log');
}
				
			

Import Binding a Company, creating the record if it doesn’t exist

The following example shows how to set the Owner Company model field with the ID of a company which has been specified by name in the import file. If the company doesn’t exist then it is created.

This example is very import, because it demonstrates how to create a related entity starting from a value specified in the Excel File.

				
					/*  $value contains the value of the current column in the import file, calling trim()
method (after casting as string type) to eliminate any space at the beginning or
at the end of the string */
$value = trim((string)$value);
/*  if the company name field specified in the import file is not empty */
if($value) {
    /*  if the company name (transformed into uppercase) doesn’t exist in DeepDesk.
    Here we are checking the keys of $companyArray created in the 'Before Run' area */
    if(!array_key_exists(strtoupper($value), $companyArray)){
        /*  a new Company object is created through the static getModel() method of the Deep class (
    via the abstract factory pattern)*/
        $companyModel = Deep::getModel('deep_company/company');
        $companyModel->setName($value);
        $companyModel->setStatus(1);
        /*  saving the company to Database after setting the name and the status (1 = Enabled) */
        $companyModel->save();
        /*  adding the company just created to the $companyArray */
        $companyArray[strtoupper($value)] = $companyModel->getId();
    }
    /*  the field owner_company_id of the CI is set here.
        The id is calculated starting from the name of the company specified in the import file */
    $model->setOwnerCompanyId($companyArray[strtoupper($value)]);
}
				
			

Global Import

In Deepser, the configuration and execution of system imports is the exclusive prerogative of administrative users.

In any case, it is possible to give the possibility of executing imports already configured and tested by administrator users to other types of backend users as well.

This possibility is provided by global imports.

Global Import configuration

The configuration of an import as a “Global import” must always be carried out by an administrator user following the configuration and testing phase of the configured import.

In fact, within an import record we find the following fields:

These fields are not visible by default on the Import Form, so to make them appear, you need to edit the Formtemplate and add them.

Field

Definition

Enable Global Import

It’s a toggle button which indicates if we want this import procedure to be visible to other users expect admin or not. By toggling “Yes” the current import procedure will be shown on the global imports grid.

Global Import Groups

It’s a multiselect field in which you can choose the user groups that will have visibility to this global import procedure.


As the first step in configuring global import settings, it is necessary to ensure that the role of the user(s) who need visibility of the import has the ‘Global Menu’ enabled and specifically the ‘Import’ action available as a resource in their role.:

Global import using

Once all the configuration has been completed, users will be able to access the global imports section directly from the global menu at the top right of the screen (icon “…”):

By clicking on the relevant section, you can access the screen with the list of all the global imports accessible:

By clicking on the desired import, it will be possible to access the details, where it is normally possible to upload a file used for the import.

Once the file has been uploaded, it will be possible to perform the import by clicking on the respective “Run” button on the right top corner:

IT Asset Management

This Course will explain everythin about ITAM Configuration and Usage, from Deepser’s own remote collector, to the various job rules and monitoring you can do to each device.

The IT Asset Management module allows you to keep an automated archive of the Assets whose information is updated and sorted automatically, it is also possible to consult and modify the data of each resource manually via the web interface.

IT Asset Models

To access the available models for the IT Asset module, go to the main menu and navigate to the “IT Asset” section:

From here, we can find various usable models. In the following articles there is a detailed description of each

ITAM Device

To consult all the devices added to “IT Asset Management” module, go to the Asset>Device section in Deepser back-end.

From there you can see the Devices and organize them into by configuring your custom grids and access the form containing their data to modify them if it is necessary.

From this section, you can manually add a device using the ‘Add Device’ button. Anyway, for this purpose, you can use the CMDB module. The difference is that the IT Asset module is designed to automatically retrieve devices, unlike the CMDB module through which management of devices is only manual.

To add a new Device by agent, you can click on the ‘Download Agent’ button (Agent installation procedure is illustrated here). Once the agent is downloaded and configured your current Device will be added as a record on the grid.

Licenses in use: Available at the top of the page, it indicates the available number of devices that can be added. In fact, the devices in this module are subject to licensing.

Device Tab & Fields

By clicking on a Device in the grid, you can access the form containing its data, such as:

  • CPU
  • BIOS
  • HDD
  • Network Interfaces
  • Operating System
  • RAM
  • installed software

In device edit or creation, the following tab and fields are available:

Device Data Tab

On Device Data Tab, there are the main information of a device. Below is the detail:

Field

Description

Name

Text field with the retrieved Device’s name.

Device Name

The retrieved Device’s name

Status

Select field with two values: enabled or disabled. Initially its value is set to enabled.

Type

Select field where you can choose a device type. It has already some pre-configured values such as: physical, virtual, other and unknown.

Subtype

Select field where you can choose a device subtype. Each subtype value is linked to a type.

Description

Text area field where can add a description for your device.

Serial Number, Model Name, Vendor Name, Domain, Last Username, Last User Domain

Text fields which are auto populated from agent, with the current device’s corresponding data.

Last Scan At

Datetime field which indicates the last time this device was scanned by an agent or remote collector.

Last Seen At

Datetime field which reflects the last time the device was observed to be active and responsive.

In Service

Select field with two values: ‘Yes’ and ‘No’, which indicates if the device still has the agent downloaded and is currently active and operational within the network.

Hardware Tab

On Hardware Tab, all device’s hardware such as BIOS, System Chassis, CPU, RAM, Network Interface etc.

All device-related hardware information is stored in different grid fields. Each grid record has an action column, which you can click to view further details on the related hardware data. 

Software Tab

Under “Software” tab, there are all software information related to the main device. We can find the following grids:

  • Operating System: Grid field which stores all the information related to the device’s operating system.
  • Software: field which stores all data about software programs installed in your device.

Users Tab

In the Users Tab you can relate client information to the device.

 

Field

Description

Owner Company, Assigned Company

Select fields with values retrieved from Company model.

Owner Group, Assigned Group

Select fields with values retrieved from Group model.

Owner User, Assigned User

Select fields with values retrieved from User model.

Monitoring Tab

Through “Monitoring” Tab, you can monitor your device’s data:

The available fields are:

Field

Description

Remote Control

Select field which allows you to connect and take control of the device remotely.

Monitoring Data

It shows a graphical representation of your device resources usage during a period of time.

Metrics

Multiselect field where you can choose the resource usage that you want to show on the graph.

Period

Select field where you can choose timeframe for displaying data.

ITAM Software

To consult software added to ‘IT Asset Management’ module, go to the Asset>Software>Software in Use section in the Deepser back-end.
On this model are saved all the software programs data, retrieved from the devices.

The software installed on collected devices is automatically added to Deepser.

You can also organize software by configuring custom grids and manually add new records.

By clicking on a Software entry in the grid, you can access the form containing its data:

 

The available fields for this module are:

Field

Description

Name

Text field with the retrieved software’s name

Vendor

Text field with the related vendor of the software

Version

Text field that indicates the current version of the software

Install Date

Datetime field which indicates the date the software was installed.

First Scanned At

Datetime field which indicates the date when the software was scanned on the device.

Identifying Number

Text field with a unique string to identify the software.

Device

Text field where it is saved the device Id connected to this  software

Description

Text area field where you can add a description for the software

ITAM Network

The Network model is designed to manage and organize network information, typically for assets or devices within Deepser. This model includes two types:
  • Subnet: This type stores information about network subnets. It helps in organizing and managing large ranges of IP addresses by grouping them into subnets. You can configure various attributes related to the subnet, such as its range and any relevant network settings.
  • IP Address: This type stores specific details about individual IP addresses within the defined subnets. It allows for the tracking and management of each IP address, including its assignment status, associated device, and any additional configuration details.

Together, these types provide a comprehensive framework for managing network infrastructure, ensuring that both broad subnet information and detailed IP address data are effectively organized and accessible.

Subnet

We can access existing Subnet or manually create one from the main menu: “IT Asset > Network > Subnet”.

By clicking on “Add IP Address” or selecting an existing record, the following screen will appear:

For Subnet editing or creation, the following fields are available:

Field 

Description 

Name 

Text field which is used to indicate the name of subnet. 

Network Address 

Text field which indicates the base address of the subnet. This field is populated by a CIDR IP address.

Bitmask 

The subnet mask in bit form, indicating the number of bits used for the network portion of the address. 

Range Start 

The first usable IP address in the subnet. 

Range End 

The last usable IP address in the subnet. 

Gateway IP Address 

The IP address of the gateway or router for the subnet, used for routing traffic outside the subnet. 

Gateway Mac Address 

The MAC address of the gateway or router associated with the Gateway IP Address. 

Subnet Unique Id 

A unique identifier for the subnet within the system 

Last Seen At 

Datetime field indicating the last time this subnet was observed or updated. 

Status 

Select field in which you can enable or disable the subnet. 

Subnet IPs 

Grid field where there are shown all the ips connected to this subnet. 

IP Address

We can access existing IP addresses or manually create one from the main menu: “IT Asset > Network > IP Address”.

By clicking on “Add IP Address” or selecting an existing record, the following screen will appear:

 
For IP address editing or creation, the following fields are available:

Field 

Description 

IPv4 Address 

Text field where IPv4 address is stored. 

IPv6 Address 

Text field that stores an IPv6 address. Allowed format for this field is the standard notation of IPv6

Subnet 

Select field with all the available subnets which can be connected to this ip. 

Device 

Select field which links the device with this ip address. 

Network Interface 

This field is used to select the network interface associated with the IP address. It could refer to a physical or virtual interface on a device. 

Status 

Select field which can ‘enable’ or ‘disable’ this ip address. 

ITAM Management

The Management model in Deepser is designed to streamline device administration by executing preconfigured scripts, tracking, and managing device updates. This model includes three distinct types: Scripting, Updates, and Jobs.
  • Scripting allows administrators to automate tasks by running predefined scripts on devices, reducing manual effort and ensuring consistency.
  • Updates enable the monitoring and deployment of software updates across all devices, ensuring they remain secure and up-to-date.
  • Jobs provide a way to schedule and manage recurring tasks or operations, offering flexibility and control over routine maintenance.

Below are the detailed operations of each type.

Scripting

We can access the “Scripting” type from the main menu: “IT Asset > Management > Scripting”

Within the Scripting type, there are two separate sections:

  • Script: In this section, you can view and manage predefined scripts that are available for execution on devices. You can also create new scripts by clicking the “Add Script” button. These scripts can automate various tasks and operations on your devices.
  • Run History: This section provides a detailed log of all script executions. It shows the history of scripts that have been run, including information such as the date and time of execution, the status of the script, and any errors or issues encountered. By clicking on individual log records, you can access detailed information about each execution, including which devices were affected and the results of the script.

These sections allow you to effectively manage and monitor script usage, automate tasks, and review the outcomes of script executions.

Script

Clicking on “Script” we can access to the list of predefined script that can be execute on your device (and cannot be modified):

However, you can also create your own script to execute by clicking on the “Add Script” button located at the top right corner of the screen: 

The fields available in the script model are the following:

Field 

Description 

Name 

The name for your script

Type 

With this field you can choose the type of your script:

•          Batch

•          Powershell

•          Bash (Linux/Mac)

Scope 

With this field you can choose if the script should be run for all system users or for the current user.

Category 1

Categories are used to categorize the script you are creating.

Category 2 

Description 

A field to describe the script you are creating.

Content

This field should contain the command you want to execute. In this field should be inserted powershell, batch or bash commands.

Execution Timeout

Waiting time before the script is marked as not completed successfully.

Arguments

With this field you can provide additional parameters to the script.

User Defined 

This field is read-only and indicates whether the script was manually created by a user.

Existing scripts have this field set to “No”.

Status

With this field you can enable or disable the script.

Script Example

Below an example of an existing script:

This script allow a user to clean up a disk with a PoweShell command. It can be identified by “Type” field (Powershell) and the “Content” which contains the commands to be sent to a device.

Execute Script

To execute a script on a device, you need to access the specific device, and at the top right corner of the screen, you can use the green “Run Script” button:

Clicking on the button will open a new screen: 

From here, you can choose to execute either a user-defined script (on the left side) or a script from the System Library (on the right side).

Clicking the “Run” button next to a script will execute it.

Additionally, the “Run History” button at the top center of the screen allows you to access the history of executed scripts (“Run History” section).

Run History

As previously mentioned, the Run History section enables users to check and verify results of executed scripts:

By clicking on a history record we can see the following information: 

Below is the detail of their operation:

Field 

Description 

Script 

History related script. 

Device 

Device on which the script was executed

Execution Status 

This field determine the execution status. 

Sent By 

The user who sent the command. 

Sent At

The date when the command was sent to the server.

Executed At

The execution date. 

Output 

The output received from the sent command.

Return Code 

Exit status or result code returned by sent command. 

Updates

We can access “Updates” type from the main menu: “IT Asset > Management > Updates”.

In this section, you can find a list of all available updates detected by the remote collector on the scanned devices. This includes:

  • Updates Available for Installation: These are updates that have been detected on the scanned devices but have not yet been installed. The list shows which devices can receive these updates.
  • Updates Already Installed: These are updates that have already been applied to the scanned devices. The list indicates which devices have successfully installed these updates.
  • Update Details: For each update, you can view additional information such as the update name, version, release date, and any relevant descriptions or notes.
  • Installation Status: See the number of devices where each update is pending installation or has been installed. This helps in monitoring the update deployment process.
  • Filter and Search Options: You may have options to filter or search for specific updates, platform and other data making it easier to manage and track updates across your IT infrastructure.

This comprehensive view helps you effectively manage and oversee the update status of your devices, ensuring that all necessary updates are applied and monitored

 

In the “Available For Devices” column of the grid, you can see which scanned devices can receive the update. The number in the blue box indicates how many devices the update can be installed on. 

Clicking on the blue box will display a list of devices on which you can install the update: 

In the “Installed On Devices” column of the grid, you can see which scanned devices have had the update installed. The number in the gray box indicates how many devices have received the update. 

Clicking on the gray box will display a detailed list of devices on which the update has been installed. Depending on the type of update, you may also have the option to uninstall it: 

Job

We can access the “Job” type from the main menu: “IT Asset > Management > Job”. Within the “Job” type, there are two separate sections:
  • Configuration: In this section, you can create, view, and manage job configurations. This includes setting up new jobs, defining parameters, and scheduling tasks. It allows you to configure how jobs are executed, including specifying details such as target devices, job types, and execution schedules.
  • Event Log: This section provides a comprehensive log of all job executions based on your configurations. Here, you can review the history of job runs, including details on the status of each job, any errors encountered, and the outcomes of the execution. This log helps in monitoring job performance and troubleshooting issues by providing insights into job activities and results.

These sections help manage and track the execution of jobs within Deepser, ensuring effective job management and performance monitoring.

Configuration 

With a Job, a user can automate the release of updates on scanned devices. To create a new Job Configuration, click on “Add RRM Job” after accessing the Configuration section: 

The following screen will appear: 

For a job configuration, the following fields are available: 

Field  

Description  

Name  

Text field that identifies the job configuration.  

Platform  

At the moment, only Windows platform are supported.   

Cron Expression  

It allows you to define the run interval of the job. 

Install Update Types 

Multiselect field through which you can choose the types of updates you want to handle with the job configuration. 

You can select the following types: 

  • Optional 
  • Reccomended 
  • Important  

Device Exp In  

Using this query builder field, you can filter the devices to be included in the job configuration. 

Device Filter (Script)  

In the scripting area field, you can define the criteria to filter the devices that should be included in the job configuration. 

It can be used for more complex filtering based on device data. 

Status  

Select field which can ‘enable’ or disable the job configuration.  

  

Event Log 

n the “Event Log” section of Management, you can view all job configurations executed according to your settings. This section contains a log of job executions: 

Clicking on a single log record will provide information about the update (or uninstalled update) on a device, details of the installed update, and the job that was executed: 

ITAM Automatic Scan Configuration and Usage

ITAM Agents

The first step to actively use the ITAM module, and then begin the automated introduction of Devices in Deepser, is the installation of the Agent.

The Agent is a lightweight Windows application that collects all available information regarding the device on which it is installed, and then systematically sending it to the server.

Once installed, the Agent can be converted in few simple steps into Remote Collector, so you can collect data by scanning the company network, or the subnet on which it is connected.

ITAM Agent Installation

To install the Agent go to the Deepser back-end, from the menu access the Asset>Device section, click on the “Download Agent” button at the top right (as shown in figure).

The installer will be downloaded.

All the information necessary to configure communication with the Server (URL, port) is contained in the name of the executable.

Run the installer (requires Administrator privileges) and, if necessary, modify the pre-filled connection parameters; finally click on the install button to start the installation.

Once the installation is complete, on the device desktop, an icon named ‘Portal’ and a new start menu entry named ‘DeepAgent’ menu will appear.

By clicking on the ‘Portal’ icon you will be redirected to the opening page of a new Ticket where the device in use will be automatically set in it. The proposed type of Ticket created through the Agent can be changed in the Portal configuration section.

To ensure installation has taken place correctly and there are no communication problems, go to the Device section of the Asset module from the Deepser back-end menu (Asset>Device).

In this section, the record representing the device on which the Agent has been installed will be displayed.

To access the Agent user interface, click on the ‘DeepAgent’ entry added to the Start Menu.

In the first tile, the one with an icon representing an “eye”, you can check the status of the ‘DeepAgent’ service.

In the second tile, the one with an icon that represents a “wifi” network connection, there is the interface for converting an Agent into a Remote Collector (the conversion process will be discussed in the dedicated section).

ITAM Remote Collector

A remote collector is a component in a network monitoring or management system designed to gather data from various devices and systems within a network. In Deepser you can configure a device as a remote collector, if that device has agent downloaded and by clicking on the button ‘Convert to RC’, within the Asset – Device model.

The first step for collecting information in Agent-less mode is to configure a Remote Collector, a small-sized Windows application, which allows you to:

  • Retrieve data from devices on the same network
  • Acquire data from the device on which it is installed
  • Send collected data to the main appliance

It is possible to configure more than one, this is necessary for particular corporate network configurations, for example, if the network is organized in subnets isolated among them.

It is recommended to install the Remote Collector on a Windows computer that can communicate through the network with as much devices as possible, in order to reduce the number of Remote Collectors needed.

 

ITAM Agent to Remote Collector Conversion

To install a Remote Collector you need to have previously installed an Agent, which can be converted into a Remote Collector through some simple steps that can be done directly from the user interface.

Currently, Deepser offers two options to archive this conversion. Manually, using the interface, or automatically, using the ‘convert’ button.

AUTOMATIC CONVERSION

1- The first step to Automatically convert a regular Agent to a Remote Collector is to open the Agent form, through Asset > Device, then select the Agent you want to convert.

2 – Then, press the Convert to RC button, this will trigger the conversion request.

3 – A Dialog will open, asking for confirmation, click YES.

3b – The request will be sent, press Enable to get to the Remote Collector Grid.

4 – If the process finished without errors, the remote collector will be available, open it.

5 – To enable the Remote Collector to work in the network, click on the Enable button.

6 – If you want to Disable the remote collector, click on Disable.

MANUAL CONVERSION

Go to the ‘DeepAgent’ entry added to the Start Menu, by clicking on it the Agent user interface will open.

In the second tile, there is the interface for converting an Agent into a Remote Collector.

To convert the Agent click on the ‘Convert to Remote Collector’ button.

At this point go to the System>Asset Configuration>Remote Collector section of the Deepser back-end.

In the grid there will be a record representing the conversion request (from Agent to Remote Collector) sent by the device, the status of the request will be ‘Pending‘.

Click on the ‘One Time Password’ cell to copy the OTP directly to the clipboard, or open the request form and copy the content of the ‘One Time Password’ field.

Once the ‘One Time Password’ has been copied, return to the Agent user interface, and paste it in the text field on the Remote Collector tab.

Now the Agent can be converted into a Remote Collector, click on the ‘Validate OTP’ button to proceed, at this point the user interface will automatically close and the background conversion procedure will begin.

Once the conversion process is finished:

  • In System>Asset Configuration>Remote Collector section in the Deepser backend, the previously created conversion request will change from ‘Pending‘ to ‘Enabled‘
  • the start menu entry will be renamed to ‘DeepAgent RC‘ (RC = Remote Collector).

The user interface of the Remote Collector displays only the status of the service, all configuration tools and controls are accessible from the Deepser back-end under the section SystemàAsset Configuration.

At this point, it is possible to configure scan jobs that will be performed by the Remote Collector, which will recover data from devices connected to the network.

ITAM Configuration

The module configuration, as defined by Deepser, is accessible from the “System > IT Asset Configuration” section and is visible only to System Administrators to ensure maximum security and control:

In this section, you can configure:

  • Device Types: Define and manage the different types of devices tracked in Deepser.
  • Device Subtypes: Specify subcategories for more detailed asset classification.
  • Scan Jobs: Set up and manage jobs for scanning devices to gather necessary data.
  • Monitoring Rules: Establish rules for monitoring scan jobs and other system activities to ensure proper functioning and performance.
  • Remote Collector Configuration: Configure settings for remote collectors to efficiently collect and manage data from devices.

These options allow for comprehensive customization and management of the asset management system to meet your organization’s specific needs.

In the configuration section of the Asset Management module, it is possible to manage types and sub-types of Assets added in Deepser.

To access their configuration, go to the System>Asset Configuration>Device Type or System>Asset Configuration>Device Subtype section in Deepser back-end.

Device Type

In the configuration section of the Asset Management module, you can manage the types of assets added in Deepser.

To access their configuration, go to the System>Asset Configuration>Device Type in the Deepser back-end.

From this section, you can configure a new device types in addition to the default ones by clicking the button in the top right corner.

Device Type Configuration

In the device type edit or creation process, the following screen will appear:

For the device type configuration, the following fields are available:

Field

Description

Name

A text field for entering the name of the device type.

Code

A text field where you can add a unique code for the device type.

Description

A text area field where you can add a description.

Position

A text field that accepts a numerical value, representing the order of this device type in the grid.

Status

A select field that indicates whether the device type is enabled or disabled, determining if it can be used for the device model.

Icon

A file uploader field where you can upload an image to be set as the icon for this device type

 

Device Subtype

In the configuration section of the Asset Management module, you can manage subtypes of assets added in Deepser.

To access their configuration, go to the System>Asset Configuration>Device Subtype in the Deepser back-end.

From this section, you can configure device subtypes for each existing device type.

Device Subtype Configuration

In device type edit or creation, the following screen will appear:

For the device subtype configuration, the following fields are available:

Field

Description

Name

Text field with device type’s naming.

Code

Text field where you can add a unique code for the device type

Type

Select field with all the Device type. You can link the device subtype with a type.

Description

Text area field where you can add a description

Position

Text field which accepts a numerical value, that represents the order of this device type on the grid.

Status

Select field which indicates if device type is enabled or disabled in order to be used on the device model.

Icon

File uploader field, where you can upload an image, that will be set as an icon for this device type.

Job Rules

By configuring Job-Rules it is possible to automatically fill collected devices fields, such as assigning the company to a device according to the network where it was detected.

To configure a Job-Rule go to the System > Asset Configuration > Scan Job > Job Rule section in Deepser back-end.

Through the query-builder ‘Device Filter’ you can define a condition, which is tested on devices; if this condition is satisfied then the device data is automatically set as defined by the query-builder ‘Set Device Values’.

In the case of multiple Job Rules, their execution order is decided on the assigned ‘Priority’ value (descending order).

Note: the rule is executed every time the Remote Collector sends data related to a device.

Scan Jobs

On this section you can find the available scan job protocols supported and configurable on Deepser:
  • SNMP: SNMP scanning involves querying SNMP agents running on network devices to gather information about their configuration, status, and performance.
  • WMI: WMI scanning involves querying Windows-based systems using WMI to gather detailed information about their hardware, software, and configuration.
  • SSH: SSH scanning involves attempting to establish SSH connections with various hosts on a network. This type of scanning is used for unix devices.
  • Ping sweep: Ping scanning involves sending ICMP echo requests (ping packets) to a range of IP addresses within a network. By analysing the responses, a scanner can determine which hosts are online and responsive.

SNMP Scan

To add a job that performs an SNMP scan, go to the System>Asset Configuration>Scan Job>SNMP section in Deepser back-end, and click the ‘Add SNMP‘ button at the top right. At this point, the form for configuring an SNMP Job will open.

Form fields have the following meaning:

Field Meaning
Name Name of the Job.
Port UDP port used by Remote Collector to communicate with devices. The default is 161.
CRON Expression Cron Expression, it is present in every type of scan, allows you to define the run interval of the job.
IP Range In this field, you can define the range of IP addresses to scan. You can indicate:•       One or more IP addresses•       One or more ranges of IP addresses•       One or more subnets, specified by CIDR notation
IP Range Exclusion In this field, you can define which IP addresses should be excluded from the scan. The compilation rules are the same as in the ‘IP Range’ field.
Remote Collector Through this Select, it is possible to declare which Remote Collector will execute the Job.
ICMP Check Through this select field, you can decide to perform an SNMP scan only for IPs that are reachable by ping.
SNMP Version SNMP protocol version used to perform the network scan, options are:•       SNMPv1•       SNMPv2c•       SNMPv3
Community For each device, the Remote Collector will attempt authentication using each of them (following the insertion order) until it gets a positive response. The community strings must be saved within the Deepser Password module.Note: In case of the SNMPv3 version, the username that will be used will be the one set in the ‘Username’ field present in the record of the Password form.
Authentication Mode Only for the SNMPv3 version, it is necessary to set the authentication mode.
Auth Protocol Only for the SNMPv3 version, indicate the possible Auth Protocol.
Priv Protocol For the SNMPv3 version only, indicate the possible Priv Protocol.
Auth Password For the SNMPv3 version only, enter the Password if the selected Auth Protocol requires it. The Password must be stored within the Deepser Password module.
Priv Password For the SNMPv3 version only, enter the Password if the selected Priv Protocol requires it. The Password must be stored within the Deepser Password module.
Status State. If ‘Enabled’ the Job will be sent to the Remote Collector to be executed.
Job Status Job execution status. It can assume the values ‘Running’ during execution by the Remote Collector or ‘Stopped’.
Job progress Progress-Bar indicating the percentage of execution of the Job.
Run Now Once the Job has been saved, using the yellow button on the top right ‘Run Now’ you can run it immediately.

Once the Job has been configured and finally executed, the collected Devices will be visible in the Asset>Device section in Deepser back-end.

WMI Scan – Windows Devices

To add a Job that performs a WMI scan go to the System>Asset Configuration>Scan Job>WMI section of the Deepser back-end, and click the ‘Add WMI‘ button at the top right.

At this point, the form for configuring a WMI Job will open.

Form fields have the following meaning:

FieldMeaning
NameName of the Job.
TypeBy this field, you can choose if the job you are configuring is a scan (‘Scan’) or the ‘Agent Deploy’.
CRON ExpressionCron Expression, it is present in every type of scan, allows you to define the run interval of the job.
IP RangeIn this field, you can define the range of IP addresses to scan. You can indicate:•       One or more IP addresses•       One or more ranges of IP addresses•       One or more subnets, specified by CIDR notationUno o più indirizzi IP 
IP Range ExclusionIn this field, you can define which IP addresses should be excluded from the scan. The compilation rules are the same as in the ‘IP Range’ field.
Remote CollectorThrough this Select, it is possible to declare which Remote Collector will execute the Job.
ICMP CheckThrough this select field, you can decide to perform a WMI scan only for IPs that are reachable by ping.
PasswordSpecify one or more passwords to access devices.For each device, the Remote Collector will attempt authentication using each of them (following the insertion order) until it obtains a positive response. Passwords must be stored in Deepser Password module.
Use LDAP ServerThis field indicates if an LDAP integration is needed.
LDAP ServerLDAP server.
LDAP Server PasswordPassword for authentication to the LDAP server.The password must be saved within the Deepser Password module.
LDAP Filter TypeYou can set one of the proposed LDAP filters or specify a custom filter.
LDAP Custom FilterCustom LDAP filter.
StatusStatus. If ‘Enabled’ the Job will be sent to the Remote Collector to be executed.
Job StatusExecution status of the Job. It can assume the values ‘Running’ during the execution by the Remote Collector or ‘Stopped’.
Job progressProgress-Bar that indicates at what percentage of execution the Job is at
Run NowOnce the Job has been saved, it is possible to run it immediately using the yellow ‘Run Now’ button on the top right.

Once the Job has been configured and executed, collected Devices will be displayed in the Asset>Device section in Deepser back-end.

SSH Scan

To configure a Job that performs an SSH scan go to the System>Asset Configuration>Scan Job>SSH section in the Deepser back-end, and click the “Add SSH” button at the top right.

At this point, the form for configuring an SSH job will open.

Form fields have the following meaning:

Field

Description

Name

Name of the Job.

Port

The port used for SSH connection. The default SSH port is 22.

Cron Expression

Cron Expression, it is present in every type of scan, allows you to define the run interval of the job.

IP Range

In this field, you can define the range of IP addresses to scan. You can indicate:

•          One or more IP addresses

•          One or more ranges of IP addresses

•          One or more subnets, specified by CIDR notation

IP Range Exclusion

In this field, you can define which IP addresses should be excluded from the scan. The compilation rules are the same as in the ‘IP Range’ field.

Remote Collector

Through this Select, it is possible to declare which Remote Collector will execute the Job.

ICMP Check

ICMP Check to YES is used to test the reachability of a host on an IP network.

Password

A multiselect password field through which you can specify one or more passwords to access devices.

For each provided password, the Remote Collector will attempt authentication in the order they are listed until it receives a positive response.

This field is related to the Deepser Password module, so you need to store the passwords you want to use in that module before they can be utilized here.

To use the passwords in this field, you must set the “Use Password” field to “Yes” in the Password record.

Status

If ‘Enabled’ the Job will be sent to the Remote Collector to be executed based on Cron Expression.

Job Status

Execution status of the Job. It can assume the values ‘Running’ during the execution by the Remote Collector or ‘Stopped’.

Progress

Progress-Bar that indicates at what percentage of execution the Job is at

Run Now

Once the Job has been saved, it is possible to run it immediately using the yellow ‘Run Now’ button on the top right.

Once the job has been configured and executed, the devices discovered during the scan will be visible in the grid under the Asset > Device section in the Deepser back-end.

Ping Sweep

To configure a Job that performs a Ping-Sweep scan go to the System>Asset Configuration>Scan Job>Ping-Sweep section in the Deepser back-end, and click the ‘Add Ping Sweep‘ button at the top right.

At this point, the form for configuring a Ping-Sweep job will open.

Form fields have the following meaning:

FieldMeaning
NameName of the Job.
CRON ExpressionCron Expression, it is present in every type of scan, allows you to define the run interval of the job.
IP RangeIn this field, you can define the range of IP addresses to scan. You can indicate:•       One or more IP addresses•       One or more ranges of IP addresses•       One or more subnets, specified by CIDR notation
IP Range ExclusionIn this field, you can define which IP addresses should be excluded from the scan. The compilation rules are the same as in the ‘IP Range’ field.
Remote CollectorThrough this Select, it is possible to declare which Remote Collector will execute the Job.
Create DeviceBy this Select field, you can decide if you want to create in Deepser the Devices that represent the scanned IP addresses by marking them as ‘In Service’.
Change Device ServiceBy enabling this option it is possible to change the service status of a device.When a previously added device is unreachable, it will be marked as ‘Not in service’. This behavior also applies to the reverse case.
StatusState. If ‘Enabled’ the Job will be sent to the Remote Collector to be executed.
Job StatusJob execution status. It can assume the values ​​’Running’ during execution by the Remote Collector or ‘Stopped’.
Job progressProgress-Bar indicating the percentage of execution of the Job.
Run NowOnce the Job has been saved, using the yellow button on the top right ‘Run Now’ you can run it immediately.

Once the Job has been configured and executed, the Devices found during the scan will be visible in the grid in the Asset>Device section in Deepser back-end.

Remote Collector

A remote collector is a component in a network monitoring or management system designed to gather data from various devices and systems within a network.

You can find more details about its complete configuration here.

To check and verify all configured Remote Collectors (RCs), go to System > IT Asset Configuration > Remote Collector. By clicking on an RC record, the following screen will appear:

For Remote Collector editing or creation, the following fields are available:

Field

Description

Device

Readonly field containing the relation to the device that originated the Remote Collector.

Name

Field for setting a custom name for the Remote Collector.

If the RC was created via agent, the name will be pre-filled based on the name of the device configured as the RC.

One Time Password

OTP Fieldautomatically created on Remote Collector creation.

It can be used for the RC configuration.

Status

With this field you can Enable, Disable or set the RC in Pending status.

On creation, the default status is “Pending”.

Monitoring

The Monitoring model provides a comprehensive system for tracking and analyzing various device metrics. It helps maintain optimal performance and stability of the IT infrastructure by allowing for timely interventions based on real-time data and predefined thresholds. 

To access the Monitoring section, navigate to System > IT Asset Configuration > Monitoring. In this section, you can:

  • Configure Monitoring Rules: Select “Rule” to set up, view, or edit monitoring rules. These rules define the criteria and thresholds for monitoring device metrics and trigger alerts or actions when certain conditions are met.
  • View Monitoring Events: Click on “Event” to review execution information and historical data related to monitoring rules. This section provides insights into rule triggers, alert statuses, and any actions taken based on the monitoring criteria.

These functionalities enable effective management of IT infrastructure by ensuring that potential issues are detected and addressed promptly, thereby minimizing downtime and optimizing performance.

Rule

By using the Rule model, you can create specific rules for monitoring different device metrics and set up alerts or ticket creation when the specified conditions are met.

Clicking on the Add Rule button will open the following screen:

For a rule configuration, the following fields are available:

Field 

Description 

Name 

Text field that identifies the rule. 

Status 

Select field which can ‘enable’ or disable the rule. 

Devices 

Query Builder field where you can filter the devices for which this rule will be applied to. 

Metrics Type 

Select field with the available metrics type of the device. 

Metric 

Select field where you can choose the metric on which the rule will be based on. 

Threshold 

This field specifies the threshold value for the selected metric. When the metric exceeds this value, the rule triggers an alert or action. 

Threshold Period 

Numeric field which sets the time period over which the threshold is evaluated. It ensures that temporary spikes or anomalies do not trigger unnecessary alerts. 

Event Code 

A unique code identifying the event executed by this rule. 

Event Impact 

Select field describes the potential impact of the event, such as ‘Low,’ ‘Medium,’ ‘High’. 

Model 

Select field where you can set a model like operation, activity, which will be created after the rule is triggered.

When a model is selected, a new query builder will appear that allows you to set the information for the model record you want to create.

Event

In the “event” section of the monitoring, you can see all the rules executed based on your configurations. Therefore, this section contains the log of the rule executions.

Clicking on a single log record we can find information about the executed rule and its related information.

This detailed view helps in understanding the context of rule triggers, evaluating the effectiveness of the monitoring rules, and troubleshooting any issues that may have arisen.

AnyDesk

To establish a connection with a remote device in the IT Asset Device section, access the main menu and go to IT Assets > Device.

Before proceeding, ensure that the target device has the required agent installed. (The agent installation process is explained here.)

From the available grid, select the device you wish to connect to:

Next, download the AnyDesk remote desktop software  on the device from which the remote connection will be initiated.

For the remote computer, the AnyDesk software installation is automatically handled by the Deepser agent.

Enabling AnyDesk Remote Control

To enable remote control via AnyDesk:

  1. Navigate to System > Configuration > IT ASSET > Configurations > AnyDesk(Remote Control).
  2. Set the Enabled field to ‘Yes’.

Instead, to disable and exclude it from the available remote connection software options, set the Enabled field to ‘No’.

Setting AnyDesk as the Default Remote Control Software

To configure Supremo as the default remote control software:

  1. Go to System > Configuration > IT ASSET > Configurations > Remote Control.
  2. Select AnyDesk as the default software.

Once configured, AnyDesk will automatically be selected from the list of available remote control options.

Connecting to the Remote Device

To configure remote access in Deepser, navigate to IT Asset > Device > Tab Monitoring > Remote Control.

Starting a Remote Session

After entering the randomly generated password from AnyDesk, it will be possible to proceed with the session.

To initiate a remote session:

  • Go to IT Asset > Device > Tab Monitoring.
  • In the Remote Control field, click Connect for the selected device.

Alternatively, you can also start the connection from the Device grid under IT Asset > Device

Supremo

To connect to a remote device listed under IT ASSET > DEVICE, access the main menu and navigate to IT Assets > Device.

To enable the connection of the device in Deepser, the agent must be installed on the device. The installation procedure for the agent is outlined here).

From the device management grid, select the desired device to initiate the connection.

The next step involves downloading the Supremo remote desktop software, which must be executed on the device used to initiate the connection to the remote computer.

On the remote computer, the Supremo software installation is managed directly by the Deepser agent.

Enabling Supremo Remote Control

To enable remote control via Supremo:

  1. Navigate to System > Configuration > IT ASSET > Configurations > Supremo (Remote Control).
  2. Set the Enabled field to ‘Yes’.

Instead, to disable and exclude it from the available remote connection software options, set the Enabled field to ‘No’.

Setting Supremo as the Default Remote Control Software

To configure Supremo as the default remote control software:

  1. Go to System > Configuration > IT ASSET > Configurations > Remote Control.
  2. Select Supremo as the default software.

Once configured, Supremo will automatically be selected from the list of available remote control options.

 

Connecting to the Remote Device

To initiate a connection to a remote device:

  1. Navigate to IT Asset > Device > Tab Remote Control.
  2. The following fields will be available:
    • Remote Control: Displays the remote desktop software being used.
    • Supremo Secondary Password: A dropdown menu to select the secondary password.

Starting a Remote Session

After entering the password generated by Supremo, you can proceed with the session:

  • Go to IT Asset > Device > Tab Remote Control.
  • In the Remote Control field, click the Connect button within the device.

Alternatively, the connection can be initiated directly from the grid under IT Asset > Device.

Configuring the Secondary Password

The Secondary Password configuration allows remote connections without requiring a one-time password for each session. This enables automatic remote connections.

To configure the Secondary Password in Deepser:

  1. Go to IT Asset > Device > Tab Remote Control.
  2. Under the Supremo Secondary Password entity, click the + icon.

3. A form will appear for creating the password.

Once saved, the password can be selected in the Supremo Secondary Password field of the device.

Setting a Default Secondary Password

To define a default secondary password:

  1. Navigate to System > Configuration > IT ASSET > Configurations > Supremo (Remote Control).
  2. In the Secondary Password field, select the desired default password from the dropdown menu.

This setting ensures that the configured default password is automatically used for all remote connections.

Knowledge Base

In Deepser you can create, organize, and share content, guides, manuals or simple Faqs using the Knowledge Base module.

The Knowledge Base is a useful tool for immediate troubleshooting, in fact they are suggested during the opening of the tickets

Reading the Knowledge Base

1 – In Deepser you can access and consult the Knowledge Base from 3 separate entry-points:

  • From backend (accessible only by Agents)
    You can access the KB from the menu in the Deepser backend by clicking on the Knowledge Base item.
  • From the User Portal
    You can access the KB from the User Portal from the menu at the top right and by selecting the item Knowledge Base.
  • From the Guest Portal
    You can access the KB from the Guest Portal from the menu at the top right and by selecting the Knowledge Base item.

2 – At this point the grid containing the Knowledge Base will open, click on the View button to open the KB you want to consult.

3 – When the Knowledge Base is opened, its description/introduction is displayed.

You can navigate through the articles via the left-hand summary.

Knowledge Base in Service Operations

To limit as much as possible that end users open Tickets for questions/problems whose answers/solutions are already present in the Knowledge Base, in the Service Operations (Tickets) there is a standard Knowledge Base field.

This field, through a select, will propose the articles related to the scope of the ticket that is being created, if any.

The articles and the Knowledge Base to which they belong, to be proposed, must be visible by the current user and in the area in which it is located (User Portal or Guest Portal).

Article Configuration in Knowledge Base

You can add or modify an existing article both from the Deepser backend (for operators) and from the User Portal.

1 – After clicking on the View button of a Knowledge Base, if you have the necessary privileges you can:

  • Consult the articles in the KB;
  • Copy (add to clipboard) links to the article;
  • Delete the article;
  • Print out the article;
  • Add a new article: Click on the icon with the symbol (+) just above the summary to the left;
  • Edit the selected article: Click on the pencil icon at the top right;
  • Attach files to the article.

1b – By pressing the pencil icon you can then edit an article

2 – At this point you will see the form for creating/editing an article.

The form fields have the following meaning:

FieldDescription
TitleTitle of Article
IdentifierIdentification code of the article. It will be used in the composition of the article URL if it and the KB to which it belongs have been made visible in the Guest Portal.
CategoryCategory. You can use it to configure suggestions to KB articles from a Service Operation (ticket).
Visibility in FrontendIf set to YES, then the article will be visible and searchable by unauthenticated users in the Deepser Guest Portal.
Visibility in the PortalIf set to YES, then the article will be visible and searchable by authenticated users in the Deepser User Portal.
Visibility AdministratorsIf set to YES, then the article will be visible and searchable by operators from the Deepser backend.
Comments EnabledAllow comments to an article.
TagsTags of the article. By default it is through tags that KB articles are offered in Service Operations.
DescriptionBody of the article.

Knowledge Base Configuration

The creation of Knowledge Base is only allowed to System Administrators, while the ability to create or modify articles of the Knowledge Base can be granted to other categories of users through the corresponding configuration form of the KB itself.

1 – To create or configure a Knowledge Base you need to access the System à Knowledge Base section from the Deepser backend.

In the next screen click on the button at the top right

2 – The form for creating/modifying a Knowledge Base will then be shown.

The form fields have the following meaning:

CampSignificance
NameName of Knowledge Base
IconPossible Knowledge Base icon
IdentifierKB identification code. It will be used in the composition of the KB URL if it has been made visible in the Guest Portal.
DescriptionDescription of the KB. It is displayed when a KB is opened before an Article is consulted.
Brief descriptionBrief description. It is displayed in the grid of the Knowledge Base section, that is the screen in which the KB are shown.
LocationLocation of the current KB inside the screen, organized as a grid, where the KB are displayed.
ColumnsNumber of columns occupied by the KB in the KB selection grid to consult.
StateState. If the status is enabled, the KB will be visible and searchable.
Visibility AdministratorsIf set to YES, then the KB will be visible and searchable by operators from the Deepser backend.
Visibility in the PortalIf set to YES, then the KB will be visible and searchable by authenticated users in the Deepser User Portal.
Visibility in FrontendIf set to YES, then the KB will be visible and searchable by unauthenticated users in the Deepser Guest Portal.
Groups View KbIn this field are inserted the groups to which give visibility of the KB.
Groups Edit KbIn this field are inserted the groups to which to grant the possibility to modify the KB (es: creation/elimination of articles).

OVERVIEW CONFIGURATION SEARCH MODULE KB

In Deepser it is possible to configure the way in which the search between the various articles is carried out, allowing to obtain better results. Various filter types are used to do this.

Knowledge Base Standard Filters

In Deepser it is possible to configure the way in which the search between the various articles is carried out, allowing to obtain better results. Various filter types are used to do this.

The proposal of articles related to the scope, for example, of the Service Operation that is being created takes place through the appropriate configuration of search filters.

The order in which the articles are proposed is degressive compared to the number of positive matches between current model and article.

FILTER ON TAGS ARTICLE

It’s the standard filter, the search looks for a match between the title of the Service Operation and the tags defined in the Knowledge Base articles.

FILTER ON PRODUCT DESCRIPTION

To filter into the “article body” (Description field) you need to change the configuration from the Systemconfigurationknowledge Base > Configurations > search from the Deepser backend.

The form fields have the following meaning:

FieldDescription
Use description in searchIf set to YES the search content (for example the title of a ticket) is searched in the body of articles.
Redirect the Search DataIf set to YES, the KB search indexes are re-created.
Maximum number of resultsMaximum number of articles proposed in the search results.

Knowledge Base Advanced Filters

Another possible search mode, which can be added to the previous ones, is the category filter.

The correspondence of the category set in the Service Operation is evaluated, with the one chosen instead in the article of the KB.

To configure this filter, you need to change the configuration of the custom field, type Kbtips, which offers the articles in the form.

CATEGORY FILTER – GUIDE

1 – Go to the System > custom Fields section of the Deepser backend and select the Deepservice – Operation model.

2 – Click on the Fields tab and on a Kbtips type field (eg Knowledge Base) to access the configuration form.

3 – Add the following php code to the custom element scripting area and click the Apply button at the top right.

				
					$element['fire_search'] = true;
$currentOperation = Deep::registry("current_model_instance");
if($currentOperation->getCategory1()){
    $filters = [];
    $filters[] = [
        'field' => 'category1',
        'value' => $currentOperation->getCategory1(),
        'condition' => 'eq',
    ];
     
    if($currentOperation->getCategory2()){
        $filters[] = [
            'field' => 'category2',
            'value' => $currentOperation->getCategory2(),
            'condition' => 'eq',
        ];
    }
    if($currentOperation->getCategory3()){
        $filters[] = [
            'field' => 'category3',
            'value' => $currentOperation->getCategory3(),
            'condition' => 'eq',
        ];
    }
     
    $element['filters'] = $filters;
}
				
			

Now the articles will be filtered based on the correspondence between categories set in the Operation and those set in the article.

Notes:

  1. Items without category are always proposed, but not having positive matches in the comparison between categories will penalize them in the order with which they are proposed.
  • If in the ticket I have selected only Category 1 = CATEGORY A’, then all the articles that have as Category 1 = CATEGORY A’ in the following order will be displayed: first those with the only Category 1 valued, then the others with any Category 2, Category 3 and finally those without any assigned category.
  • If in the ticket I have selected Category 1 = Category A’ and Category 2 = Category B’ then all the articles that have as Category 1 = Category A’ and Category 2 = Category B’ will be displayed in the following order: first those with Category 1 and Category 2,  then possible with Category 3 and finally those without assigned category.

List

In Deepser, lists represent data organized into groups.

The options created inside a List can be displayed using a custom field, which is linked to the List.

Also, list can be used as filter for grids.

Note that, Lists always have a unique “key” parameter for each item.

This means that the order of each item inside the list is important.

Introduction to lists

In Deepser, lists are organized data groups that can be used as options for custom, system fields and filter fields for grids.

By their nature, Lists always have a list of items marked by a unique “key” parameter in the list, but which could be repeated in other lists.

Lists are a useful tool for creating custom fields as they allow you to create options for them without the need to write code, which makes it easy to create custom fields even for users less accustomed to programming.

Creating a new list

To create a new list, you will need to go to the menu: System-> Tools ->Lists.

At this point, you will need to click on the “Add List” button at the top right.

The following screen will then open:

Below are the fields with their associated description:

FieldDescription
CodeUnique code name of the list.
NameName of the list you are creating. 
Compare List  This field is a system field, it can be ignored in the normal Deepser usage.
Compare List self-exclusion  This field is a system field, it can be ignored in the normal Deepser usage.
ImageImage associated with the list you are  creating
StatusStatus Of The List You Are  Creating

Once you have filled in the fields, you will need to click on “Save List” or on “Save And Continue Edit List”.

At this point, the list will have been created.

Example Creating a List

Suppose you want to create a list with name “Demo List” which will contain as different values possible versions of demos to be submitted to the customer. In particular, we will create an In Presence demo and a remote demo.  

To do this, you will need to go to the menu: System -> Tools ->Lists.

At this point, we click on the “Add List” button.

Here we are going to fill in the “Code” field with the code of the list, this field by convention must be all lowercase and instead of spaces underscores must be used.

In our example, We will enter in the “Code”field” : “demo_types”.

Now we give a name to the list by filling in the “Name” field, in our example we will enter: “Demo Types

Now we leave all the other Default fields and click on the “Save List” or Save And Continue Edit List” button.

Creating list items

To create the actual elements that will become the options in a list-based select, we must go to the list in which we want to go to create the elements.

At this point, we go to the “Values ” tab and click on the “Add Value” button.

The following screen will then open:

In the Key field that indicates the unique key of the value, we are going to enter a number that must be different from those already present in the list. In our case, we enter 0.

Now, In the label field, we enter “Live Demo”.

After that we have to click the “Save List Value” button if we do not have to add other values or the “Save And New” button if we have to create others or the “Apply” button.

At this point you create in the same way a new entry called “Online Demo” with key set to 1.

Finally, on the main screen of the list, click on the “Save List” button to save the list.

At this point, the list will have been saved with the created items.

List Values and Model Visibility

After the creation of a list with its list values, a question may have popped in your mind:

“How can I use the list values to filter other fields and pilot the autofill, for example, of a ticket?”

All you need is called “Model Visibility”.

Let’s create an example.

You will need to go to the menu: System-> Tools ->Lists and then click on the “Service Operation Status” list.

The following screen will then open:

Now let’s imagine we want to filter some Service Type based on a selected value from that list, for example the “New” value.

To do this, click on the “Add Model” button.

The following screen will then open:

Here a simple description of each field:
FieldDescription
Model AliasThis field represent the name of the model in which you want to apply the filter.
StatusThis field set the status enabled or disabled.
Expression with query builderUsing a query builder, it’s simple to set filters.
From the drop-down select which field you want to filter and set the condition.
Expression (Script)Use a custom code to set custom filters.

In this way, we created a filter for the Status value “New” inside the Service Operation Model.

Inside the query builder we set that the Status value “New” can be displayed only for service Type equal to “Incident”.

Once you have filled in all the fields, you will need to click on the “Save” or “Apply” button.

Use a list as the basis of a custom field

After the creation of a list with its list values and a model visibility, another question may have popped in your mind:

“How can I set the same list value inside different models, for example the Service Module and the CMDB Module?”

“How can I use list as a data source?”

To use a list as a data source of a custom field, you will need to go to the menu:

System -> Custom Fields.

Here, we will select the template on which to create or modify the custom field in question.

In our case, it will be the “DeepService – Operation” model.

Once we have clicked on the model we want to modify, we go to the “Custom Fields” section, here we will send you to click on the “Add Field” button.

The following screen will then open:

We configure the “Column Name” field as demo_types.

We configure the “Name “field as “Demo Types”.

“Column Type” we set it to “integer”.

Instead, we set “Element Type” to List.

At this point in the field that will have appeared “List Code” select the list created in the previous point.

Finally, we set the field “status” to “Enabled”.

In the end, click on the “Save Field” button or on the “Apply” button.

After all, the field will have been created.

By entering the field in a form template, you will now notice that the values of the field will correspond to those of the list.

To add the field from a formtemplate you can refer to the guide on form templates which can be accessed by clicking here.

Password Management

This Course will cover Everything about The Configuration of Deepser’s Password Manager, From Shared Passwords settings, to system related configurations.

Deepser through the Password Module allows you to manage company passwords in a centralized way, managing visibility and permissions.

Each password is saved securely in the database, encrypted with a custom passphrase.
It is also possible to manage at group/user level the visibility or the ability to modify/delete the above mentioned passphrases. The modification of a password will therefore be visible to each user and/or group that has access to it.

The single passwords can also be associated to each Deepser module, through a Custom Deeppassword field.

PRIVATE PASSWORD

Deepser also allows the creation of private passwords, accessible only by the user who made them. The creation of these passwords can also be made accessible to end users through the appropriate portal.

Configuring a Password

1a – Access the Password module from the main Deepser menu.

1b – Else access it through the drop-down menu of the user portal.

2 – Click on the Add Password button

3 – You will see the form for the password creation.

The fields have the following meaning:

FieldMeaning
NameBrief description of the password.
UsernameUsername.
AddressAddress of the device /URL of the site
CompanyField used to connect the password to an existing Deepser company.
PasswordThe Password to store.
GenerateButton to generate a random password.
Key File contentCryptographic key to be stored, inserted as text content. (e.g. to store an API key).
View Groups/View UsersAllows to select multiple groups or individual users who will be able to view the password.
View and Edit Groups/View and Edit UsersAllows to select multiple groups or individual users who will be able to view and edit/delete the password.
Use Groups/Use UsersIt allows to select multiple groups or individual users who will be able to display the password in the forms that will use it, implemented by means of a custom Deeppassword field.
Use PasswordEnable the display of the password within the modules that implement it.
HiddenIt makes the password not recoverable by passphrase from users, but still usable internally by the software, for example for scanning.
StatusIndicates the status of the password (Enabled/Disabled).
Expiration DateDefines an expiration date for the password, can be implemented as a reminder for escalation rules. When the expiration date is reached, the Expired field is automatically set to ‘Yes’.
ExpiredIndicates if the password has expired.
Updated byIndicates which user is responsible for the latest password update.
Is privateIndicates if the password is private.
DescriptionDescription and/or additional notes on the password.
CategoryThe category field can be valorized only if there are categories visible to the DeepPassword model.

3a – To generate a random password, click the Generate button.

3b – Select the relevant parameters, enter a length, and then click on Generate.

3c – Fill in the relevant fields (in the example a password is configured for a cloud service, then the fields Name, Username, Password will be highlighted, this will be visible to all groups, but only Second Level IT administrators can change it).

Note: To the left of the Generate button there is a security indicator for the password entered.

4 – Now the password is correctly saved and viewable by selected users and groups

 
 

Using a Password

In Deepser you can access passwords in two ways, through the main menu, or, if properly configured, through the user portal.

1a – Access the Password module from the main Deepser menu.

1b – Access through the drop-down menu of the user portal.

2 – At this point you will see the grid with all the passwords that you are allowed to view

3 – To copy the address or username field, simply click the value of the line, to copy the password instead, click the icon with the two sheets, to display it click the eye icon.

Note: If you have the necessary permissions, the password quick change button will appear on the left of each line.

Private Password

Deepser gives to each user the ability to store private passwords.
These passwords are defined as private , since they are only available to the user who created them, and even system admins don’t have access to them.

Private passwords are encrypted when set , and decrypted when read, using a passphrase defined at user level.

So to ensure greater security, each user can define their own passphrase.

ENTER A PRIVATE PASSWORD – HELP

In Deepser you can access passwords in two ways, through the main menu, or, if properly configured, through the user portal.

1a – Access the Password module from the main Deepser menu.

1b – Access through the drop-down menu of the user portal.

2 – Start the password creation  procedure (see the dedicated guide in the academy), but set the Is private field to yes.

Note: It is possible to make a private password public, but not the other way around.

3 – A new button will appear, Reset user passphrase, this allows you to choose a passphrase at user level.

4 – After clicking the button, choose a personal passphrase, then save it.

5 – Now a personal passphrase is set, so you can proceed storing your private password by clicking Save.

Note: Not all view and use fields are present, because only the user who configured the private password can have access to it.

Password System Configuration

SYSTEM PASSPHRASE

To guarantee the confidentiality of saved public passwords, Deepser encrypts them before saving them into the database, using a key defined by the Admin, called Passphrase.

Before defining any password, you must enter a passphrase, otherwise an error message will be generated. To do this, simply go to System Configuration-> Password-> Configurations

This is the system configuration screen for passwords.

The meaning of the fields is as follows

FIELDExample / Notes
PassphraseThe key with which passwords will be encrypted and decrypted.
Password Timeout in SecondsTime in seconds that defines when the user in the password page will be logged out.
Minimum Password LengthIndicates the minimum length of the passwords (the minimum assignable is 3 anyway).
Default Password View/Edit GroupsIndicates the group that will have read/edit acces to the password by default, if no group was specified when creating the password.
Default Password View/Edit UsersIndicates the user who will be given access to read and change the password by default, if no user was specified when creating the password.  
Enable Private PasswordGives users the ability to create private passwords.
Enable Private Password GroupsIndicates which groups of users can save private passwords.

Once the passphrase is configured, you can configure the minimum length of the password and, for security reasons, the time after which any user on the password page is logged out. This allows you to prevent malicious users from accessing passwords, in case a user has accidentally forgotten the computer logged in on the passwords screen. After the time elapsed , Deepser will automatically logout the user from the web application.

DEFAULT PERMISSIONS

Deepser, through the fields Default Password View/Edit Groups and Default Password View/Edit Users allows to establish a default behavior, in case no user or group is indicated as viewer or editor, in the password creation form.

PRIVATE PASSWORD

Deepser allows users to save private passwords that are not accessible or editable by any user except the creator.

These passwords can become public, but the opposite is not possible. Enable Private Password to ‘Yes’ also allows end users to create passwords through the portal, all passwords entered through the user portal are private.

Note: You may need to make the Is Private field visible in the password creation template form to do this by editing the template using the edit button.

Finally, drag and drop the field and save.

Enabling Password Manager Portal

In Deepser the password manager is not present in the user portal by default, so you need to enable it.

NOTE: The end user cannot change or create new public passwords, but only view them.

1 – Go to the Deepser portal system configuration, via System->Configuration->Portal->Configurations

2 – Expand the Password label, activate the display in the portal by setting Enabled to yes and select the groups for which it should be enabled, then save.

3 – At this point, in the portal there will be available the Password section

3a – The password manager in the portal will look like this.

4 – In the portal, to change the default grid, or add a new one, go to the Password section of the main Deepser sidebar.

5 – Here it will be possible to add new grids by clicking on the ‘+‘ button, or edit existing ones by clicking on the edit icon.

Note: To learn more about editing grids, see the dedicated section.

Custom Deeppassword fields

In Deepser you can configure custom fields of Deeppassword type, these allow you to associate one or more passwords to a particular module.

In this guide the goal is to associate passwords to the various CIs.

1 – Access the custom fields in the system configuration

2 – Select the module where you want to make the passwords accessible (In this case DeepCMDB – CI).

3 – Proceed to the creation of a new custom field by clicking on Fields -> Add Field.

4 – Fill in the form with a name and label of your choice, and set as Column Type: Don’t create DB column and as Element Type: Deeppassword, then save the field.

5 – At this point you just need to edit the form template of the CIs in the CMDB to make the field visible, and then press  save.

Note: To learn more about the topic “editing template forms”, go to the appropriate section of the Academy.

6 – At this point you can select one or more passwords to connect.

6a – Once the changes have been applied, you can click on the box below the select with the password name , to view or modify it, or on the ‘+‘ symbol to add a new one.

Password Audit

Deepser, to ensure the security of passwords, and track their usage, implements a Password Audit, which provides a grid, where you can view all activities involving public and private passwords.

For each password activity, deepser keeps track of various data, including the user name, the action taken on the password, the user agent of the browser used, the url used to access the password and the ip address of the machine used.

1 – To access the password audit, go to System->Tools->Log Viewer-> Audit->Password.

Relations

Deepser allows you to configure relations between entities.
Deepser relationships are intended to “connect” records of the same entity or records of different entities.
Think about mapping the correspondence between a ticket and a ci, perhaps to define this ci should be repaired or a ci that can belong to more users, such as the key of an office.
In this course we will deal with the relations in Deepser and their management.

Relationships can be on the same model or between two different models, based on a field in one model and on another field in the second model, fields used as keys for the relationship.

Relations can also be inverse, which allows you to trace back from the related entity to the main one.

To be used on the user side, relationships need a field “Relation grid”.

This allows you to define the link between entities of the relationship.

Note that this component will not automatically retrieve the relation, but it’s necessary to define it manually in the field itself which relationship should be managed by this field.

Using a Relation Grid field

In this guide, we will see how to use a relation grid field to add and remove elements related to an entity.

ADD A CI TO AN OPERATION

To add a ci to an operation you will need to go in the operation itself, for example an incident with a specific ID.

Inside the ticket, there is a TAB called Relations.

After the creation of a custom relation between the CMDB model and Operation model, the following screen will then open:

You will need to click on the “Add” button.
Now the following screen will open:

Here we will have to go and tick the box placed in correspondence of the platform that we want to go to d add and select from the menu, located at the top left the item “Add”:

Now we must click on “Submit” to confirm.

At this points a confirmation alert will appear on which we will have to click the “OK” button:

At the end we must click the close button, located in the lower right corner and we will see the added platform:

REMOVE A CI FROM AN OPERATION

To remove an operation will be necessary to click on the check placed at the operation to be
removed and from the menu placed in the upper left corner of this field we must go to click the item “Delete”:  

At this point a confirmation popup will appear on which we will have to click on the “Ok” button:

In the end, we will see that the operation will have been removed correctly.

Configuring a Relation

In Deepser, you can configure an entity relationship.

To do this you will need to go to the menu: System->Relations.

In the screen that will open you will need to click on “Add Relation”.

At this point the following screen will open:

Below are the fields with their meaning:

FieldDescription
Source ModelMain model of the relation
Destination ModelThe target (or related) model of the relation.
StatusStatus of the relation.
If “Enabled” then it will be visible and usable otherwise it will not be visible and usable.
NameRelation name, from Destination to Source Model
Opposite NameInverse relation name, from Source to Destination Model
Source Id FieldHere we are setting which field must be used to identify the source model.
For example, we can choose “entity_id”.
Source Label FieldsHere we are setting which fields we want to show up in the source relation grid.
For example, we can choose “Name”.
Source Label SeparatorHere we are setting the separator of the label fields in the source relation grid.
Source Search FieldHere we are setting which field must be used to search the source model.
For example, we can choose “Name”.
Dest Id FieldHere we are setting which field must be used to identify the destination model.
For example, we can choose “entity_id”.
Dest Label FieldsHere we are setting which fields we want to show up in the destination relation grid.
For example, we can choose “Name”.
Dest Label SeparatorHere we are setting the separator of the label fields in the destination relation grid.
Dest Search FieldHere we are setting which field must be used to search the destination model.
For example, we can choose “Name”.

EXAMPLE CONFIGURATION OF A RELATION

In this guide, we are going to configure a relationship between an operation and the Ci.

To do this, you will need to go to the System -> Relations menu.

At this, we click the “Add Relation” button.

In the screen that will open, we will set  the field  “Source  Model”:  “DeepCmdb – Ci” and in the field “Destination Model”: “DeepService – Operation”.

In the “Name” field we will enter the name we want to give to the relation.

In the “Opposite Name” field we set the name for the opposite relation. For example, if we want to link an element of the CMDB to a ticket, we need to use the opposite relation.

Now, in the “Source” section we configure the “Source Id Field” field with the value “entity_id” and “Source Search Field” and “Source Label Field” field with “Name”.

Finally, in the “Destination” section we set the “Dest Id Field” field with the value “entity_id” and “Dest Search Field” and “Dest Label Field” field with “Title”.

As a last step, we must click on the “Save” or “Apply” button.

Relation Grid Creation

To create a relation grid, we need to create a custom field that will allow us to interact with the created relation.

To create the custom field, you need to go to System -> Custom Fields.

Here we will have to choose the model “DeepService – Operation”, in which we want to add the custom field.

Now we will have to go to the “Fields” section, here we will have to click on “Add field”.

The following screen will appear:

Inside “Column Name” field we set the field name we want to display. In this case “Relation Operation to CMDB “

In the “Column Type” field we set “Don’t Create DB Column”.

In the “Element Type” field we set “Relationgrid”, the type of element we want to create.

After these steps, in the “Relation” we select in the drop-down menu the relation that we have previously created.

Now you will have to click on the “Save” or “Apply” button.

Now, you can add this field called “Relation Operation to CMDB” to the form template of Operation.

For the configuration, see these article called “Form Template Configuration” and “Column Configuration“.

Modifying relation using a custom event.

In Deepser you can modify relationships using an event, as we will see in the following example.

This can be useful for creating relationship management flows including, for example, an approval phase.

EXAMPLE: MODIFYING A RELATION USING A CUSTOM EVENT

In this example, we are going to create a flow for the management of the relation between users and the Ci class Location.

The objective of this report will be to keep records of which end users can access to the Ci class “Location”.

Suppose that a type of special service is created (Access Management), opening a ticket of this type users can ask to obtain access to a “Location”, once the request is sent, and it will be evaluated by the backend operators and if approved the relationship between the requesting user and the location will be mapped.

CONFIGURING THE RELATION

To create a new relation, we must go to the menu: System -> Relation.

Here we are going to click on the “Add Relation” button.

In the screen that will open, we will configure the “Source Model” field as “DeepCmdb – Ci”.

Now we will set the field “Destination Model” to “DeepAdmin – User”.

In the Source section, we are going to configure the field “Source Id Field” with the value “entity_id”.

In the “Source Label Fields” field and in the “Source Search Field” field, we will enter “Name”.

At this point in the “Destination” section, we will set the”Dest Id Field” field as “user_id”.

Finally, in the field “Dest Search Field” we set “username”.

As a last step, we are going to click on the “Save” or “Apply” button to save the relationship.

CUSTOM FIELD CONFIGURATION ON CIS

To create the custom field, you will need to go to System -> Custom Fields.

Here we will have to choose the model “DeepCmdb – CI”.

Now we will have to go to the item “Fields”, here we are going to click on “Add Field”.

At this point, the following screen will open:

We compile the fields as follows.

In the “Column Name” field, we are going to configure the value “cust_ci_user_relation”.

In the “Column Type” field, we are going to configure the value “Don’t Create DB Column”.

In the “Element Type” field, we are going to configure the value “Relationgrid”.

In the “Label” field, we are going to configure the value “Allowed Users”.

In the “Status” field, we are going to configure the value “Enabled”.

In the “Relation” field, we are going to select the name of the relationship created previously.

At this point, We must click on the “Save” or “Apply” button to save the field.

CUSTOM EVENT CONFIGURATION

As a prerequisite for this step there is the configuration of a type of special service with related form templates on the user portal side, you can find the documentation about it at this link:  link.

To create the custom event for the population of the relation, we must go to System -> Custom Fields.

Here we will have to choose the model “DeepService – Operation”.

Now we are going to configure a new custom event by going to the “Events” Tab and then clicking on the “Add Event” button.

Note that in this example we will use the “cust_ci_id” field (check the field names to fit your configuration, in case you do not use the default fields).

At this point, the following screen will open:

Here we are going to fill in the “Name” field with the name we want to give to the event and the “Type” field with the “After Save” value.
At the end of the field “Method” we enter the following code:

				
					$operationType = 13;
$approvedOperationStatus = 8;
 
/**If this is setted  and the type id is Access Managemt**/
if($this && $this->getData('type_id') == $operationType ){
    /**Check if the request is approved**/
    if($this->getStatus() == $approvedOperationStatus){
        /**Load the Relation**/
        $realtion = Deep::getModel('deep_relation/relation')->load(5);
        /**Get Ci id**/
        $ciId = $this->getData('cust_ci_id');
        /**Load the requester user**/
        $requester = $this->getRequesterUser();
        /**If the CIid is set and the requester is not an empty object**/
        if($ciId && $requester && $requester->getId()){
            /**Adding The requester user in relation with the ci**/
           $realtion->addRoles($requester->getId(),[$ciId]);
        }
    }
}
				
			

As a last step, you will need to click on the “Save” or “Apply” button to save the event.

Opposite relation

In Deepser, you can define an inverse relationship with respect to the parent relationship.

This allows you to trace back from the entity related to the main one.

Taking as an example the report addressed in the previous point of this guide, using the Reverse Relationship it will be possible to connect from the user to all the Cis to which he has access.

CONFIGURING AN OPPOSITE RELATION

In this example, we will see how to configure the relationship seen in the previous point of this guide to be able to trace from the user to all the Location class ci to which it has access.

To do this, you will need to go to System -> Custom Fields.

Here we will have to choose the “DeepAdmin – User” template.

Now we will have to go to the “Fields” item, here we are going to click on “Add Field”.

At this point, the following screen will open:

We compile the fields as follows:

  • “Column Name”: here we are going to define “cust_user_ci_relation”.
  • “Column Type”: here we are going to define “Don’t Create DB Column”.
  • “Element Type”: Here we will enter “Relationgrid”.
  • “Label”: here we will enter “Authorized Locations”.
  • “Status”: here we are going to define “Enabled”.
  • “Relation”: here we are going to select the name of the relationship created previously.

As a last step, we must go to the “Extras” tab and configure the “Opposite” field on Yes.

At this point, We must click on the “Save” or “Apply” button to save the field.

Now it will be sufficient to add the field in the template form of the users, and we will be able to view and interact with the inverse relation.

Column Configuration

In Deepser it is also possible to configure which columns should be visible in the Relation Grid.

To configure it, first you need to configure the form template and add the custom field to it.

See this article “Configuring a Relation“.

After this, inside the operation in the TAB “Relation”, the following screen will appear:

At this point, we have to go to the “Edit” button. Once clicked, the following screen will open:

Now you can add columns or remove them by dragging the entries corresponding to the columns from the “Available Columns” section to the “Visible Columns” section and vice versa.

Now, you will need to click on “Save” or “Apply” to save the new configuration.

Finally, you will see that the column has been added correctly.

Relation Graph View

Relation Graph View is used to create a visual interface of relation module. This module has two entities:

  • Graph View
  • Palette

Graph View

Graph View is the main entity where we will configure the relation. This entity is found inside the Relation module. When we go to that entity we can see the following image:

  • To create a new entity just click the button “Add Graph View”.
  • To edit an existing entity just click the row of that entity.
  • To see the graphical view of a relation, click the open graph button of the respective entity.

Creating / Editing Graph View

When we create or edit a graph view entity the following form will be shown.

The available fields are inside the graph view tab:

  • Name – the name of this relation.
  • Model Alias – main model of this relation.
  • Relation – existing simple relations.
  • Expressions – filtering the entities that will be displayed inside this relation.
  • Related custom fields – add new related models to this main model.
  • Default Layout – the layout of the relation.
  • Palette Id – the colors and descriptions that will be used inside of this relation.

The available fields inside the permissions tab:

  • View groups – which group can view this relation.
  • View users – which user can view this relation.
  • View and edit groups – which group can view and edit.
  • View and edit users – which user can view and edit.

Open graph view button

When we click the “open graph view” button we will be redirected to the following page

Here you can see on the left side all the entities that we have predefined in the above configuration and the relations between all the entities. You can drag these entities to your needs. On the right side we have a menu with 5 main parts:

  • Node search and focus: is used to search for a specific entity or focus the view to the selected one.
  • Legend: is used to show the colors of the relationships between entities. If we click one element inside the legend, we can toggle on and off the relations lines.
  • Layout: is used to change the layout of the relation.
  • Exclude models: is used to hide/show models that are available inside this relation.
  • Export button: when clicked downloads the current view as a png file.

Right click on an entity

When we right click on an entity inside the graph view the following popup will appear.

We can see 4 elements inside the popup:

  • Open form – opens the form of this entity on a new tab.
  • Relations – relations is used to append existing relations to the graph view. When we select this option a new modal will show where you can select a relation. On this selection only the relations that have the same Src Model as the entity we right clicked.
  • Entities in current node – is used to show the entities that are present inside this current model. When clicked the following modal will show. Here you can see all the fields of the selected entity that are separate models inside Deepser.
  • Related entities – is used to show all entities that are associated with the current selections. This shows only the models that have this entity assigned.

Palette

Palette is used to make this relation more understandable by using colors and icons. Palette is located inside the relation module.

We can add a new palette by clicking Add Palette or edit an existing palette by clicking the respective row. Inside the palette form we have 3 main elements:

  • Name – name of this palette.
  • Status – status of this palette.
  • Palette items – all available items inside the palette.

When we click the Add Palette Item button or click one of the existing items the following window will show up:

Here we can see the following fields:

  • Model alias – which model these items will apply to.
  • Expressions – is to add more filters even between the elements of the same model.
  • Status – the status of this item.
  • Priority – the entity that fills 2 or more items filters will get the style of the one with the higher priority.
  • Label fields – what will be shown inside the graph view.
  • Label separator – how these labels will be separated.
  • Icon – what icon will these entities have.
  • Color – what color these entities will be displayed with.
  • Tooltip – what data will be shown when we hover an entity inside the graph view.

Service Management

This course will give you some precious information on the configuration of the Service Module.

The service Module is a flexible yet powerful way to recreate a modern service management solution in Deepser, for istance, Ticketing is a feature served through this module.

Introduction to Services in Deepser

In Deepser the Services are the services offered by the organization.

The Service module collects all the data of user requests, sorts records by priority, expiration date, creation date and organizes them by Type, and category.

The user portal shows the types of requests that can be submitted by end users to the support service.

In the backend instead, there will be in the sidebar a Service section That will count all the types of service that the group is enabled to view.

Service Operations

The Operation model contains all the necessary information for the management of the ticketing process. Every Operation, based on the Type field, can become, for example, a support request, an issue, a change request, etc.

Service operations are taken from the ITIL Methodology, where Service Operation is that part of service management that is concerned with ensuring that services are delivered effectively and efficiently. The lifecycle phase of Service Operation includes fulfilling user requests, resolving reported failures, troubleshooting problems, and performing routine operational activities.

Typically, Operations can be opened by End Users in the portal, and then managed by the internal support team, or by Operators, directly in the Deepser backend.

 

Creating a Service Operation

This guide covers all the basic steps required to create a new Operation.

1 – The creation of a new Service Operation can be done from the portal, or from the Backend (accessible only by operators).

1a – From the User Portal, select the type of request you intend to open.

1b – From the menu present in the Backend, access the grid of the type of service concerned (in the example you want to create a Generic Request).

Note: By default, Deepser implements Incident, Request, Problem, Change service types, but each environment can be configured with custom Service Types.

2 – From Backend, press the Add Operation button (the name ‘Operation‘ varies according to the name of the service type involved).

3 – If the Operation has been created through the User Portal (End Users do not have access to the Backend), then a different Form Template will be loaded.
The standard Form Template from the User Portal looks like this:

The meaning of the fields available by default is the following:

FieldMeaning
TitleThe title of the Operation. Usually a brief description.
CategoryThe Operation category. It is a fundamental piece of information for managing the assignment to the workgroups and for cataloguing the scope of the required activity in a precise manner.
UrgencyThe Urgency indicated by the user of the Operation
DescriptionThe detailed description of the ticket, with any additional information.

3a – Fill in all relevant fields, then press Save to save the Operation and close the insertion template, or press Apply to save but stay on the page. Pressing Reset will cause the values to be restored to the last saved version.

Note: The figure represents the template displayed by default when opening the request on the backend side.

4 – After saving, the operation will be visible within the user portal.

4a – Or it will be visible on the backend side within the selected Service Type.

5 – The Delete button allows the physical deletion of the ticket*, while Close causes it to be closed (Status = Closed). Print Report activates the generation of a ticket report.

PHYSICAL AND LOGICAL TICKET ELIMINATION

Each Operation can be deleted. This happens if you set the Operation in a state of class “Deleted”. Requests deleted in this way are not physically elminated from the DataBase, but are only logically elminated (they will be visible in the Deleted grid). To physically delete a request from the DataBase, use the Delete button. This button permanently deletes the record from the system, which will no longer be recoverable.

Adding Comments, Activities, Attachments and Tasks to Operations

This guide will cover other standard actions in Operations, such as inserting a comment, a WorkLog, attaching a file or adding a Task.

1 – The access to the Service Operation can be made from portal, or from Backend (exclusive access to operators).

1a – Select the Affected Operation within the Users portal.

1b – Or select the Operation through the Deepser Backend.

2 – This guide uses as an example the insertion of elements in the operation from the Users portal, to get an overview of how this looks in the Backend, please refer to the Admin section of this Academy.

ADDING A COMMENT

To enter a comment, scroll down to the Comments tab, and click on Add Comment

Note: To explore this topic further, please see the dedicated section in the academy.

ADDING A WORKLOG

To enter a work activity, scroll down to the Comments tab, and click on the Work Activity tab, then on Add Activity.

Note: To explore this topic further, please see the dedicated section in the academy.

ATTACHING A FILE

To attach a File, scroll down to the Comments tab, and click on Upload a file, or drag and drop the file into the Drag and Drop area.

Note: To explore this topic further, please see the dedicated section in the academy.

CREATING A TASK

To add a task, scroll down to the Comments tab, and click on Task.

Note: To explore this topic further, please see the dedicated section in the academy.

Service Operation Main Fields

The Service Operation fields are organized in Tabs. The default tabs are Main Data, Details, Closing Info, Activity/Attachments, Email, History, Relations and SLA .

In the following article, we will see the meaning of the main fields of an Operation, those present in the Main Data Tab.

The meaning of the fields is the following:

CampMeaning
TitleThe title of the Operation. Usually a brief description.
CategoryThe Operation category. It is a fundamental piece of information for managing the assignment to the workgroups and for cataloguing the scope of the required activity in a precise manner.
StatusThe current state of the Operation. It is a fundamental data for the management of the life cycle of the request.
PriorityThe priority of Operation, as the perception of importance given by the operators who are working it.
UrgencyThe Urgency of the Operation, as the perception of importance given by the user who submitted it.
CompanyThe company requesting the ticket. It is automatically filled in according to the company to which the Requester belongs.
RequesterThe requesting user of the Operation. In case the ticket originates from an incoming email, and this email is not assigned to any user, it is equivalent to the address from which it was received.
DeviceDevice, among those present in the CMDB, to which the ticket refers.
DescriptionThe detailed description of the ticket, with any additional information.

OPERATION STATUSES

Operation statuses are used by default to track the lifecycle of tickets individually.

Every Status belongs to a Class, a simpler logical grouping.
The default classes for Deepser states are the following:

ClassMeaning
OpenStatuses that belong to this class indicate that the request has not been resolved and has yet to be processed.
ClosedStatuses that belong to this class indicate that the request has been resolved, therefore the processing is finished.
DeletedStatuses that belong to this class indicate that the request has been logically eliminated, either because it was rejected or because of input errors.

The status field, by default, can take the following values :

StatusClassMeaning
NewOpenThe request has just been created and has not yet been processed.
In processOpenThe request is in process.
ClosedClosedThe request has been processed and completed.
ReopenedOpenThe request was previously closed, but reopened as a result of, for example, a non-resolving solution or a user complaint.
Stand-ByOpenThe request is on hold.
DeletedDeletedThe request was deleted logically, either due to an entry error, or due to a refusal by an operator, to continue processing.

Service Operation Additional Fields

The Service Operation fields are organized in Tabs. The default tabs are Main Data, Details, Closing Info, Activity/Attachments, Email, History, Relations and SLA .

In the following article, we will see the meaning of the additional fields of an Operation, those in the Details, Closing Info and History tabs .

DETAILS

This tab contains various system data, below is the Tab, with the meaning of the various fields present by default:

FieldMeaning
Submit UserUser who entered the request into the system (may be different from the Requester User, i.e. the user who is actually requesting a service). Consider the example of a secretary who submits the request on behalf of their manager. In this case the Submit User is the secretary, while the Requester User is the manager.
Requester UserUser who is actually requesting a service.
Assigned GroupAssignee Group, which is the work team in charge of processing the request.
Assigned ToAssigned user of the request. Typically it is an Agent or a Key User. Deepser also allows assignment to end users, in case they have activities to perform to complete the request.
MailboxThe email box that will be used to send notifications regarding the Operation. If empty, the system default email box (if configured) will be used.
ArchivedEach Operation can be archived, for example, at the end of the year you can archive all the closed Operations of the previous year so that they will no longer appear in the default grids (they will be visible in the Archived grid).
DeletedEach Operation can be deleted. This happens if you set the Operation in a state of class “Deleted”. Requests deleted in this way are not physically elminated from the DataBase, but are only logically elminated (they will be visible in the Deleted grid). To physically delete a request from the DataBase, use the Delete button. This button permanently deletes the record from the system, which will no longer be recoverable.
Created AtDate of creation in the system of the record.
Updated AtDate the record was last updated in the system.
Closed AtDate the record was closed in the system. If a record goes from a closed to a re-opened status, then this date is cancelled.
Archived AtDate the request was filed.
Updated ByUser who last updated the request.
Deleted AtDate of logical elimination of the request.

CLOSING INFO

This tab contains the data useful for closing, such as the solution and the expiry date of the Operation. Following is the tab with the meaning of the various fields present by default:

FieldMeaning
Due DateTicket Expiration Date.
SignatureSignature, done by mouse, generally of the user who resolved the ticket.
SolutionDescription of what allowed the ticket to be resolved.

HISTORY

This Tab contains a grid with the history of all changes made to Operation.
Each edit is grouped by operating user, and shows for each field, the value before saving, and the new value inserted.

Service Operation Activities, Relations, Email and SLAs

The Service Operation fields are organized in Tabs. The default tabs are Main Data, Details, Closing Info, Activity/Attachments, Email, History, Relations and SLA .

In the following article, we’ll look at the meaning of fields integrated with other Deepser modules, those in the Activity/Attachments, Email, Relations, and SLA tabs.

To learn more about how each module works, see the dedicated sections of the Academy.

ACTIVITIES/ATTACHMENTS

This Tab contains Comments, WorLogs, Attachments, Tasks, and offers the possibility of remote control via TeamViewer.

The meaning of the areas is as follows:

AreaMeaning
TeamViewerIt offers the ability to make a remote control session with the TeamViewer account configured on Deepser. At the end of the session there is a possibility to enter a corresponding workLog with the duration of the call.
ActivitiesIt is divided into comments and work activities. According to the selected Tab it is possible to insert a Comment or a Work activity.
TaskAllows you to enter and view all tasks related to the ticket.
AttachmentsAllows you to attach files and documents to the ticket.

EMAIL

In this tab there is a grid that shows all the email messages related to the ticket, complete with body, subject, date and information about the recipient and sender addresses.

Messages can be:

  • Inbound: Via email rules, these messages can generate Operation, or comments, etc.
  • Outbound: Shows all Mail Notifications generated by tickets.

RELATIONS

In this Tab there is a grid that shows all tickets in relation to the current one.

SLA

This tab shows a grid with all timers configured to calculate SLAs.

However, the timers must have been configured correctly for Operations.

Service Types

The types of service in Deepser are used to distinguish the various types of requests that can be managed, and also associate visibility rules for groups or users based on the types of service.

To manage the visibility for groups about the types, please refer to the appropriate lesson that can be reached by clicking here.

Service Type Creation

To create a new type of Service you will need to go to the menu: System ->Service  Configuration ->Types.

At this point it will be sufficient to click on the “Add Type” button located  in the upper right corner.

The following screen will open:

Below is a table with the fields and their meaning

FieldDescription
NameIt is the name we will give to the Service type .
PositionRepresents the location where we will display the service type within the “Service” tab in the backend. If you leave Deepser empty it will automatically associate the position 0,in the case of types of service with the same position Deepser  will order them from the one with a minor entity id to the one with a greater entity  id.
Frontend Visibility  Indicates whether this service type will be visible in the public portal
IconIcon that we will associate with the service type to make it more easily identifiable
StatusStatus Of The Service Type. If the status is Active then the type will be displayed and usable otherwise it will be neither  visualizable  nor  selectable  when  opening  or  modifying  a ticket.
GroupsIndicates which groups will be able to see this type of Service. Note: if a group is not present among those enabled to this type, users of that group will not see the type of service, nor if the user is the requester or the asignee. In addition, you can also specify the pseudo group “All Groups” as a group To indicate that the type must be visible to all users in all groups.
DescriptionDescription of the type of service.

Once you have filled in the fields, Simply click the “Save” or “Apply” button to confirm and save the new type of Service.

Routing rules

The Service module of Deepser provides the routing functionality to manage the needs of Automatic ticket assignment based on one or more fields to suit all needs.
In this lesson, we will deal with the configuration and management of this fundamental aspect of the ticket management flow in Deepser.

 

Configuring Routing Rules

In Deepser you can create rules to manage automatic ticket assignments, this technology in Deepser is called Routing Rules.

You can exclude a specific ticket from the routing mechanism by using the “Disable Routing” flag, this field is not by default exposed in the formtemplate but is present between the system fields.

Configuring a Routing Rule

To configure a Routing Rule, you will need to go to the menu: System -> Service Design -> Routing.

At this point, you will need to click on the “New Rule” button.

The following screen will then open:

Below are the fields and their Meaning:

NameDescription
NameThis will be the name we will give to our Routing rule.
Continue CalculationThis field will indicate whether after evaluating this rule and obtaining a positive result from it, you should continue to process the other routing rules.
InputThis field is a query builder that allows you to filter tickets by defining under what conditions this rule should be applied.
Input (Script)This is the corresponding scripting side of the input field; it allows you to programmatically define the conditions to be verified on the tickets for them to be processed by this rule.
OutputThis field is a query builder that allows you to define the ca values to be configured on the ticket if and only if it meets the conditions provided in the input field and / or in the Input field (Script).
New Values (Script)This is the corresponding scripting side of the input field; it allows you to programmatically define the values to be set on the ticket if and only if it complies with the conditions provided in the input field and / or in the Input field (Script).

Routing Rule Creation Sample

Suppose we want to assign to the user “SYSTEM ADMIN” all the tickets of type “Incident” (id: 1)

To configure a Routing Rule, you will need to go to the menu: System -> Service Design -> Routing.

At this point you will need to click on the “New Rule” button.

The following screen will then open:

In the field “Name” we enter “Assign To Admin Every Incident”.

Now let’s configure the query builder “Input” like this:

We configure the query builder “Output” as follows:

At the end, we click the “Save” button.

To enable the rule on the main screen of the routing rules, we must click on the word “Disabled” in correspondence with the rule we want to enable. To deactivate a specific rule, we must do a similar procedure on the word “Enabled”.

Advanced Routing Configuration

You can also define routing rules by scripting.

Let’s say you want to write the previous routing rule using scripting.

To do this, we go to the menu: System -> Service Design -> Routing.

Here we will have to click on the “New Rule” button.

Now the following screen will open:

We enter as a name “Assign To Admin Every Incident”.

In the “Input (Script)” field, we enter the following code:

				
					//if the current operation is an incident, return true else return false
if($model->getData('type_id')==1){
    return true;
}
else{
    return false;
}
				
			

In the field “New Values (Script)” we enter the following code:

				
					//setting the Assigned username to admin, admin is the username of "System Admin"
$model->setData('assigned_username','admin');
//Returnning the model
return $model;
				
			

At this point, we click the “Save” button.

As a last operation on the main screen of the routing rules, we click on the “Disabled” inscription corresponding to the rule we want to enable.

SLA

The Sla module is the tool that allows to keep an eye on the Service Level Agreement in a graphic and easy to understand way.
In this course we will treat all that concerns the Sla in Deepser.

The SLAs or Service Level Agreements. They are basically timing, usually contractual or internal, which define the timing within which certain actions must be carried out: for example, within how long from the receipt of a ticket an operator must give feedback to the customer or within how long it must be closed.

SLAS IN DEEPSER

Deepser provides a S.L.A. module that allows you to easily manage these times by showing them on the tickets and allowing you to create personalized goals also3 according to the customer, priority or several concomitant factors.  

Calendar

Sla calendars are the basic tool that allows Deepser to correctly process timelines and deadlines for terms of service.
In this lesson we will cover sla calendars in Deepser in more detail.

Calendar Definition

In Deepser the sla calendars are used to define the working times.

Since the SLAs allow you to define objectives within which actions must be carried out, the calendars allow Deepser to tread these objectives taking into account any midweek holidays or non-working days or weeks of suspension of activities for the company.

Note that Deepser already has a default calendar for SLAs, but it is advisable to check its configuration since the working week may vary depending on the country or company conventions.

Create a new calendar

To create a new calendar, you will need to Go to the menu: System -> Service Design -> Sla -> Calendar

At this point, you will need to click on the “Add Calendar” button.

Now both will open the following screen:

To proceed to create the calendar, you will need to fill in the “Name” field, set the correct Timezone and click on the “Save” or “Apply” button to save the calendar.

Work Week Configuration

To configure the working week, you will need to Go to the menu: System -> Service Design -> Sla -> Calendar

At this point we will have to click on the calendar that we want to go and edit.

To configure the work week, you will need to configure the Working Week section.

To do this it will be necessary to fill in the first field with the day we want to configure in this case on Monday, in the second field we will enter the start time of Activity, in the third field the minutes of start of activity.

Similarly, in the third and fourth field, we will enter the time of end of activity.

To configure the afternoon working hours, we proceed in the same way.

At this point, the result will look like this:

We can now proceed in the same way for all working days of the week.

Once you have finished this step, you can click the “Save” button to save your changes.

Configuring Holidays and Business Suspension

To configure public holidays, you will need to go to the menu: System -> Service Design -> Sla -> Calendar.

At this point, we will have to click on the calendar that we want to go and edit.

Now in the Holidays section.

We will configure the first field with the name of the holiday, in this case “Christmas”, in the field next to it, we set the date through the selector that will appear, to confirm it will be necessary to click on the “Add” button.

Once done, the result will look like this:

It will be possible to proceed in the same way for all the public holidays present.

Finally, you will need to click on the “Save” button to save the Changes.

Metrics

Metrics in Deepser represent the type of goal to be achieved: for example, responding to a ticket within a certain time, resolving a ticket in a certain time interval, or defining how much time should pass between first-level and second-level support.
In this lesson, we will discuss metrics in more detail.

Defining Metrics

The metrics in Deepser are the real counters that Deepser will use to manage and display the time of the Sla.

Deepser can handle numerous metrics, and the metrics will only start when the “Start” condition of the metric is evaluated as true, the metric is considered concluded only when the “Stop” condition.

Creating a Custom Metric

To create a Custom metric, you will need to go to the menu: System->Service Design->Sla->Metric.

At this point, you will need to click on the “Add Metric” button.

At this point, the following screen will open:

Below are the fields with their Description:

NameDescription
NameThe name of the Metric.
ModelModel on which this metric will be evaluated.
StatusStatus Of The Metric, If Enabled” it will be evaluated otherwise it will not be evaluated.
DescriptionDescription of the Metric.

After configuring the fields, You can click on the “Save” button to save the metric.

Example of creating a metric

Suppose you want to create a metric that is applied to the operation model, that starts counting the time when a ticket is in a new state and ends when the ticket is closed.

To create a Custom metric, you will need to go to the menu: System -> Service Design -> Sla -> Metric.

We create a new metric by clicking on “Add Metric”.

We set as “Name”: “Time to close”.

In the field “Model” we set “DeepService – Operation”.

In “Description” we can configure a description at our discretion.

At this point, the query builders “Start” and “Stop” will have appeared.

Now let’s configure the query builder “Start” as follows:

Now in the Stop query builder, we enter the following configuration:

At this point, we save the metric by clicking the “Save” or “Apply” button.

Note that before the metric becomes operational it will be necessary to define goals, we will see how to define the goals in the next lesson.

Goal

The goals in Deepser are the objectives that the metrics must achieve.
More than one goal can be taken for the same metric depending on the parameters needed. In this lesson we will see more in detail the goals in deepser.

Goals in Deepser

The goals in Deepser are metric’s objective, they allow you to define by when a certain metric must be concluded.

For each metric, multiple goals can be defined depending on the customer, the priority of the ticket or any other necessary field.

CONFIGURING A GOAL

To create a custom goal, you will need to go to the menu: System -> Service Design -> Sla -> Metric.

Click on the metric on which we want to apply this Goal.

Once you have opened the metric screen to add a goal, you will need to click on the “+” button in the “Goal” section.

At this point, the following screen will open:

Below are the fields with their Meaning:

NameDescription
NameName we will give to the goal
CalendarThe calendar on which this goal will be set, normally the default calendar is used, however any of the available calendars can be selected.
TargetTime within which this goal must be executed.
PositionPosition in the list of goals (in case there is more than one this field indicates in which order we want to display it).
ExpressionQuery Builder that allows you to define a condition for which this goal will be applied for example we can have a specific goal that will apply for a single company.

At this point once you have filled in the fields you will need to click on the “Save” button to save the goal and click on the “Save” button also of the metric to save the updated metric.

Goal Creation Example

To create a custom goal, you will need to go to the menu: System -> Service Design -> Sla -> Metric.

Click on the metric on which we want to apply this Goal.

Once the metric screen opens, to add a goal, you will need to click on the “+” button in the “Goal” section.

At this point the following screen will open:

In the “Name” field we set “Goal Acme Intenational”.

In the Calendar field we set the calendar created in the previous lessons, in this case “Demo Calendar”.

In the “Target” field we set 1 hour.

The position field can be left blank, in this way the position will be determined automatically according to their ids.

In the “Expression” field we set:

At this point once you have filled in the fields you will need to click on the “Save” button to save the goal and click on the “Save” button also of the metric to save the updated metric.

Task

In Deepser, tasks represent activities that must be carried out.

Task can be associated to a ticket or it can be associated to other entities as an element of the CMDB module.

For example, it can represent a series of steps that must be carried out for the maintenance of a specific element of the CMDB module.
In this course we will cover how to organise activities using tasks in Deepser.

Tasks in Deepser

 

In Deepser, tasks represent activities that must be done.

Task can be assigned to a user and can be created from other Deepser entities.

In addition, they can also be viewed only by some users through the group rules.

Tasks can be seen by backend users by clicking on the appropriate section.

An example, it can be associated to a ticket with a series of steps that must be completed to bring the ticket itself to resolution.

 

Creation of task type

The tasks in Deepser as mentioned in the previous article are divided into categories.

In this article, we are going to analyze the procedure necessary to create a new type.

CREATING A TASK TYPOLOGY

To create a type of task, you will need to go to the menu: System->Tools->Task->Task Type.

At this point, the following screen will open:

 

Now you will need to click on the “Add Type” button.

Now the following screen will open:

Below are the fields and their value:

FieldDescription
NameThis field represent the name of the task type.
PositionThis field represent the position that this type will have in the list of tasks.
ClassThis field represents the class. There are 3 types of tasks: Task, Contact, Phone.
For a generic task, we recommend the task class.
StatusThis field set the status enabled or disabled.
Icon ClassThis field allows you to define the class icon of this type of task.
Icon ColorThis field allows you to define the color icon of this type of task.
Enabled ModelsThis field allows you to define on which Deepser entities these tasks will be visible (and  associated).
Form ExpressionThis field allows you to define the form that will open when you click the button to create a new task. Note that if this field is empty, the form for creating a new task will also be empty.
For the configuration of this field you can refer to the course Developer task available at this link
https://docs.deepser.com/courses/deeptask-advanced/lessons/task/topic/form-configuration-of-task-types/
Form Portal Expression  This field allows you to define the form that will open when you click the button to create a new task in the user portal.
Note that if this field is empty, the form for creating a new task will also be empty.
For the configuration of this field you can refer to the course Developer task available at this link (as above)

Once you have filled in all the fields, you will need to click on the “Save” or “Apply” button.

Example creating a Task class

In this example, we are going to create a task class.

Use  “Font Awesome” for the  icon class.

Note that this example will produce a task class without a form expression.

So,the form, that opens when you click the task creation button, will be empty.

To configure the form, please refer to the corresponding guide in the Task Developer course accessible at this address (as above).

To create a type of task you will need to go to the menu: System -> Tools -> Task -> Task Type.

At this point, the following screen will open:

Now you will need to click on the “Add Type” button.

Now the following screen will open:

In the “Name” field, we are going to enter “Demo Task”.

We can leave empty the “Position” field.

Now, let’s configure the “Class” field as “Task”.

Now set in the “Icon Class” field the value “fab fa-centercode”.

In the “icon Color” field, we now enter the desired color, in our case”#7FFFB7″.

Finally, select “Deep Service – Operation” in the “Enabled Modules “field to create task inside the Service Module.

As the last step, we must click on the “Save” or “Apply” button.

At this point, the task class will be saved and will become visible inside tickets.

Form configuration of task types

In this guide, we will see how to configure the form of the task type created in the previous lesson.

To start the form configuration, we must go to the menu System->tools->Task->Task Type.

Here we must select the typology created in the previous lesson.

At this point, we are going to enter in the “Form Expression” field the following code:

				
					$this->addField(
    'title',                                                //unique identification name of the field.
    'text',                                                 //type of the field
     array(
        'label' => Deep::helper('deep_task')->__('Title'),  //label of the field
        'name'  => 'title',                                 //name of the label
        'required'  => true,                                // if the filed is required
        'class' => 'required-entry',                        // css class for the field.
     )
);
$this->addField(
    'description',                                          //unique identification name of the field.
    'textarea',                                             //type of the field
     array(
        'label' => Deep::helper('deep_task')->__('Description'), //label of the field
        'name'  => 'description',                                //name of the label
        'required'  => false,                                    // if the filed is required
        'autogrow' => true                                      
     )
);
				
			

Now in the field “Form Portal Expression” we are going to enter the following code:

				
					$this->addField(
    'title',                                                //unique identification name of the field.
    'text',                                                 //type of the field
     array(
        'label' => Deep::helper('deep_task')->__('Title'),  //label of the field
        'name'  => 'title',                                 //name of the label
        'required'  => true,                                // if the filed is required
        'class' => 'required-entry',                        // css class for the field.
     )
);
$this->addField(
    'description',                                          //unique identification name of the field.
    'textarea',                                             //type of the field
     array(
        'label' => Deep::helper('deep_task')->__('Description'), //label of the field
        'name'  => 'description',                                //name of the label
        'required'  => false,                                    // if the filed is required
        'autogrow' => true                                      
     )
);
				
			

At this point, it will be possible to click on the “Save” or “Apply” button.

The result is shown below:

Task Global Grid

The global task grid is a configurable grid that allows you to view all the tasks that have been created in the system. This can only be reached from the backend.

You can go to the grid from anywhere in Deepser in the following way:

At the top right you can find the 3 dots: by clicking on them you will see the Task items and the Work Activity item.

 

By clicking Task then we will access the grid that if not configured will show the following fields:

FIELDNOTES
ActionThrough a floating window, the entity in which the relative task is contained is opened (for example, the ticket in which the task is contained).
IdThe numeric and unique id that identifies the task.
StatusThe status of the task.
TypeType of task.
Model AliasThe template that contains the task.
Owner UserThe user who owns the Task.  By default it coincides with the user who created it.
Assigned UserThe user who is assigned to perform the task.
Assigned GroupThe group that is assigned to perform the task.
Portal VisibilityVisibility of activity in the front-end. By default, tasks are not shown in the user portal.
Started AtThe date that indicates the start of the activity.
Ended AtThe date indicating the end of the activity.
Created byThe user who created the task.
Created atThe date and time that indicates the creation of the task.

VISIBILITY

The global task grid has preset visibility. In fact, a Key User or Agent user who accesses the grid will have visibility only in tasks that fall within at least one of the following cases:

  • The user created the task
  • The user owns the task
  • The user is assigned the task
  • The user is a member of the task assignee group

A user with an Admin role, on the other hand, will have visibility of all the tasks without any preset filter.

Task Global Grid Configuration

EDIT GRID FIELDS

You can access the global grid configuration for tasks through the edit button below.

Inside we could choose which fields to display and which not:

  • the available columns column lists all fields that are not shown in the grid
  • In the Visible Columns column, all the fields that are currently shown in the grid will be listed and we could choose in what order they will be shown in the grid.

To insert or remove fields from the grid, you can simply use the arrows at the ends of the fields.

To change the order of the fields shown you can use the Drag & Drop, then simply drag the fields.

By then clicking on one of the displayed fields, it is possible to define whether it is possible to make the field sortable, filterable and / or multifilterable in the case of a select field through the relative checkboxes.

 

COLLECTION OF TASKS DISPLAYED IN GRID

Within the grid in which we are located it is possible to define the collection of tasks that must be retrieved and shown in the grid through the appropriate Query Builder.

For example, you can view only the tasks that have been placed within the tickets by setting the following control in the Query Builder: Model equal DeepService – Operation.

 

MASS ACTIONS AND EXPORTS

Through the special checkbox Massive Actions, you can activate the massive actions in the grid.

Massive actions allow you to modify one or more tasks  through a grid selection. The massive action that is currently implemented by default is that of elimination.

Please Note: Elimination through massive action will result in a physical deletion to the database. Deleted tasks can no longer be recovered.

Through the Enable Export checkbox, on the other hand, it is possible to enable the export of the data displayed in the grid in XLSX or CSV format.

Once the export is enabled, a field will be shown in the grid that allows you to choose the format in which you want to extract the tasks and a button to export them.

Through the export will be extracted in the desired format the data of the tasks that are shown in the grid.

At the export click you will be shown a popup that will ask if you want to export only the tasks visible at the time of export or whether to export all the tasks.

Task Global Grid Advanced Configuration

It can often be useful to set the same value to several different tasks. In these cases, the use of massive actions is effective.

At the moment, the only massive action already prepared by the system in the global task grid is that for the (physical) elimination of one or more tasks.

You can still configure a custom massive action by accessing the grid change. Below the Mass Action checkbox is the </> button that allows the opening of the custom PHP script area.

The following example shows the custom code that implements a massive custom action to massively change the state of one or more different tasks.

The code must be inserted directly into the custom PHP script area.

				
					// retrieve all states from the list task_task_status as associative arrays
$taskStatusArray = Deep::helper('deep_list')->loadListValues('task_task_status')->toOptionHash();
 
// initialize html component
$this->addMassActionItem('status', [
    'label' => 'Change Status',
    'additional' => array(
        'status' => array(
            'name'   => 'status',
            'type'   => 'select',
            'class'  => 'required-entry',
            'label'  => 'New Status',
            'disable_js_select' => true,
            'values' => $taskStatusArray,
        )
    ),
    //callback is the method that contains the logic of the action
    'callback' => function() {
        /** @var Deep_Grid_Model_Grid_Massaction_Callback $this */
        /** @var Mage_Core_Model_Resource_Db_Collection_Abstract $collection */
        $collection = $this->getGrid()->getModelInstance()->getCollection();
         
        //$this->getIds() returns the id of the selected tasks
        $collection->addFieldToFilter('entity_id', ['in' => $this->getIds()]);
         
        // $collection contains the instances of the selected tasks and we iterate on them
        foreach($collection as $task){
            //$this->getValue() contains the id of the new status, the selected one
            //set the new status
            $task->setStatus($this->getValue());
            //save the task
            $task->save();
        }
    }
]);
				
			

By entering this script, you can then select one or more tasks and change their status to the selected one.

Workflow

Based on the ITIL framework, a service request and/or a change request can cause the generation of a workflows.

By definition, a workflow is the sequence of steps involved in moving from the beginning to the end of a working process.

Workflows allow companies to create consistent, standardized work and standardized workflows help companies operate effectively to reach their business goals.

Deepser, the ITSM software, allows you to generate a working process, e.g. an approval process, using the Approvals module and the Flow module.

Workflow Overview

Based on the ITIL framework, a service request and/or a change request can cause the generation of a workflows.

By definition, a workflow is the sequence of steps involved in moving from the beginning to the end of a working process.

Deepser, the ITSM software, allows you to generate a working process, e.g. an approval process, using the Approvals module and the Flow module.

In this course, we are going to explain how to create an approval process using the Flow module in Deepser.

 

Flow Designer

By definition, a workflow is the sequence of steps involved in moving from the beginning to the end of a working process.

The module that allows you to create a workflow is the “Flow Designer” module.

After opening your Deepser Backend portal, by clicking at “Flow” module and “Designer”

And the following screen will open:

The Flow Designer is where you can create a workflow.

In the upper section we can find the TRIGGER section which represents the starting point from which the approval process stars running.

In our example, your supervisor wants that an approval process starts when a ticket (or Operation) changes its status into “In Approval”. In this case, the trigger will be the change of the status.

In the below section, inside a red square, we can find the FLOW section which represents the approval process itself.

To build the FLOW section, located at the right, there are variables that can be dragged and dropped from right to left inside the trigger section and inside the flow section.

Therefore, it’s simple to choose visually which set of variables you need in order to create your process flow.

Located at the top right, there are

  • button “Status”: enables or disables the flow process.
  • button “Edit” : shows you the flow properties.
An interesting flow property is the “Export” function.

By clicking the button “Export”, the following screen will open:

By inserting an encryption key, you can export in a .txt file.

If you want to use the property “Import”, the button “Import” is shown in the main page of the Flow Designer Module (see the first image).

In the next article we are going to explain how to configure the TRIGGER section.

Flow Trigger

In this article we are going to analyze the Flow Trigger block.

The “Trigger” block is the only existing building block in all flows.

It is essential for the configuration of flows as it determines under what conditions a flow will have to be executed.

In the flow form, the trigger field can be configured to perform the associated flow in the following ways:

  • Model – Created
  • Model – Updated
  • Model – Created or Updated
  • Model – Deleted
  • Cron
  • API

Below we will analyze the possible macro configurations for the trigger field:

MODEL – CREATED

If the trigger block is configured in Model – Created, the associated flow will be executed when a Deepser entity, specified in the “Model” field as in the figure below, is created (e.g., when creating a ticket).

It will also be possible to define more specific conditions for the entity that will be created in order to perform the associated flow.

For example, let’s say we want to perform a flow when creating an “incident” type ticket, to do so we will have to configure the field in this way:

At this point you will need to click the Save button in the “Trigger” block to save the block itself.

MODEL – UPDATED

If the trigger block is configured in Model – Updated, the associated flow will be executed when a Deepser entity, specified in the “Model” field as in the figure below, is modified.

It will also be possible to define more specific conditions for the entity that will have to be modified in order to perform the associated flow.

It will also be possible to define whether the flow associated with the trigger should be executed only once or more using the “Run Trigger” field:

Below is a list of the values that this field can take on and their meaning:

  • Once For Model, in this case the associated flow will only be executed once for each entity.
  • Only If Not Currently Waiting on Model, in this case the associated flow will be executed only if the associated flow is not currently awaiting approval on the same entity.
  • Always, in this case the associated flow will be executed each time the associated entity is updated.

For example, let’s say we want to perform a flow when modifying an “incident” type ticket, to do so we will have to configure the field in this way:

At this point you will need to click the Save button in the “Trigger” block to save the block itself.

MODEL – CREATED OR UPDATED

If configured in Model – Created or Updated trigger, the associated flow will be executed when a Deepser entity, specified in the “Model” field as in the figure below, is created or modified.

It will also be possible to define more specific conditions for the entity that will have to be modified in order to perform the associated flow.

It will also be possible to define whether the flow associated with the trigger should be executed only once or more using the “Run Trigger” field:

Below is a list of the values that this field can take on and their meaning:

  • Once For Model, in this case the associated flow will only be executed once for each entity.
  • Only If Not Currently Waiting on Model, in this case the associated flow will be executed only if the associated flow is not currently awaiting approval on the same entity.
  • Always, in this case the associated flow will be executed each time the associated entity is updated.

For example, let’s say we want to perform a flow when creating or modifying an “incident” type ticket, to do so we will have to configure the field in this way:

At this point you will need to click the Save button in the “Trigger” block to save the block itself.

MODEL – DELETED

If configured in Model – Deleted trigger, the associated flow will be executed when a Deepser entity, specified in the “Model” field as in the figure below, is deleted.

It will also be possible to define more specific conditions for the entity that will have to be modified in order to perform the associated flow.

Below is a list of the values that this field can take on and their meaning:

  • Once For Model, in this case the associated flow will only be executed once for each entity.
  • Only If Not Currently Waiting on Model, in this case the associated flow will be executed only if the associated flow is not currently awaiting approval on the same entity.
  • Always, in this case the associated flow will be executed each time the associated entity is updated.

For example, let’s say we want to perform a flow when eliminating an “incident” type ticket, to do so we will have to configure the field in this way:

At this point you will need to click the Save button in the “Trigger” block to save the block itself.

CRON

If the trigger is configured in Cron, the associated flow will be executed at a time interval established by the cron expression.

For example, let’s say we want to run a flow every 5 minutes, to do so we will have to configure the field like this:

At this point, you will need to click the Save button in the “Trigger” block to save the block itself.

API

If the Trigger block is configured as an “API” type, the associated flow will be executed when an API call is made on its endpoint URL.

You can obtain the endpoint URL after the saving of the flow. Clicking on it you can copy all the URLs.

In the “API Trigger” block, you can also configure as many inputs and outputs as you want.

As an input parameter, you can pass the following types: String, Integer, Array, or Attachment.

As an output parameter, you can configure the flow to obtain the following types: String, Integer, Decimal, Datetime, Boolean, Array, a single model, or an entire collection.

You can act on the usability of the created flow by configuring the following fields:

FIELD

DESCRIPTION

Enable Group

With this field, you can use the flow to a specific group.

Enable Group

With this field, you can enable using of the flow to a specific user.

Enable End User

With this flag, you can enable using of the flow to the end-users.

You can make different HTTP request methods using this trigger type of API, such as post, get, delete, and put.

 

API Flow Trigger – Example

On this page we will explain how to setup a Flow with an API Trigger for a CRM Account creation on Deepser.

For example, when trying to make a post request, to create a record, you have to give all the inputs provided in the API trigger block, to the request Body.

Also, the names of the inputs should match:

				
					{
   "name":"My Company Example",
   "website":"www.deepser.com",
    "phone": "000 111 2222"   
}

				
			

For the model to be created you must add an action of type “Create Record” and give as a rule expression all the values from the request body.

To get the output you need from the API, choose the logical block “Assign values to API Outputs”. The output types that you give on this block should be the same as the types on the Trigger.

The output is returned as a JSON object from the response and it contains all the outputs that you define in the Trigger section (in our case, the “entity” section of the object) and other generic information related to the executed flow (“context” section of the object).

				
					{
    "output": {
        "result": {
            "name": "My Company Example",
            "website": "www.deepser.com",
            "phone": "000 111 2222",
            "created_at": "2024-07-10 12:37:14",
            "created_by": "admin",
            "current_version": 1,
            "updated_by": "admin",
            "company_id": 0,
            "updated_at": "2024-07-10 12:37:14",
            "entity_id": 6
        }
    },
    "context": {
        "status": 3,
        "depth": 1,
        "flow_header_id": 1,
        "flow_id": 15,
        "source": "trigger",
        "created_at": "2024-07-10 12:37:14",
        "updated_at": "2024-07-10 12:37:14",
        "entity_id": 31,
        "current_node_id": 1,
        "status_label": "Completed"
    }
}

				
			

Workflow – Stage Set

A question may have popped in your mind:

“How can I create a workflow that is divided into several steps?”

If you want to create a workflow divided into various steps, another important module is the “Stage Set” module.

After opening your Deepser Backend portal, by clicking at “Flow” module and “Stage Set” module

And the following screen will open:

By clicking the button “Add Template”, located at the left in the middle of the form template, the following screen will open:

Here is where you can create each step in which you want to divide your process flow.

The Template structure contains fields that express:

NameDescriptionNote
Namerepresent the name of the stagefor example “In Approval”.
Labelsrepresents the status that can occur during the execution of the stage process.-The status called “Completed”, which means that the stage “In Approval” has been completed.
-The second status is called “Skipped”, which means that the stage “In Approval” has been skipped, and so on.
Durationrepresent the temporal reference for each stage 

The final oucome will be:

In the next article we are going to explain how to view the flow execution.

Workflow – Executions

A question may have popped in your mind:

“How can I view all the steps and processes executed into a workflow?”

In Deepser inside the “Flow” module there is a section called “Execution”.

After opening your Deepser Backend portal, by clicking at “Flow” module and “Designer” module

And, by clicking the “Executions” tab located at the top right, the following screen will open:

Here is shown the number of times when the flow process called “Flow Approval Multi Stage” has been executed.

The first execution was completed, instead the second execution is set in status “Waiting”, which means that the flow needs to be approved or to be refused.

Inside the second execution the following screen is shown:

In this example, we can see that the flow process is still waiting into a specific stage and inside a specific block of action.

Approval workflows

Deepser, the ITSM software, allows you to generate a working process, e.g. an approval process, using the Approvals module and the Flow module.

In this course we will cover how to view, approve or refuse an approval process using the module Approvals in Deepser.

Approvals Overview

By definition, an approval process is a type of workflow which comprises a series of steps that a work must pass to be approved.

The steps typically involve different departments and employees who review the work and either approve or reject it. When one department approves or rejects, the work then flows either back to the previous step for edits or forward to the next step for further approval.

Approval processes allow companies to create consistent, standardized work and standardized workflows help companies operate effectively to reach their business goals.

For example, imagine a new employee has joined your company.

She/he needs to have access to some application software and a workstation with a PC.

She/he can’t start working until you give her/him access to it.

Your supervisor set up an approval workflow and ask you to approve the approval process.

You can open your Deepser user portal at “My Approvals” section:

And the following screen will open:
In the next article we are going to see what there is inside an approval request.

Approval by email 

In order to send emails with approval process, it is needed to go to “Ask for approval” block and set to “ON” the “Enable Email Approval” flag.

It is also necessary to enable “APPROVER – APPROVAL needed” email event, so that you receive an email with approval buttons.

Portal Approval Structure

In the previous article we have seen how to view an approval request inside the User Portal.

In this article we are going to explain the structure of the approval request.

After opening your Deepser user portal at “My Approvals” section, the following screen will open:

By clicking the approval request, the next screen will open:

The Approval structure contains fields in read only mode that express:

NameDescriptionNote
Model Aliasrepresent the model from which the approval process starsIn our example, your supervisor has created a ticket (or Operation) from which an approval process started.
Titlerepresents the name of our approval process 
Due Daterepresent the expiration date during which the approval process must be approved or refused 
Statusrepresents the condition of the approval process 

Inside the “Approval items” section is shown a grid with the Empowered end user or Backend user responsible for accept or refuse the approval workflows.

Inside the “Related Model Form” section is shown the recap of the Deepser entity linked to the approval process. In our example is shown the Operation or “ticket” that has triggered the approval process.

Therefore, the Empowered End User or Backend user can read the Title, the Category, the Status, the Assigned Group and the Description of the ticket related to the approval process.

After doing that, the EEU or Backend user can simply Approve or Reject the approval process, respectively with the Green or Red Button located at the top right.

Approval Usage 

Approval by email

After correctly configuring the flow and email event (click here for more details), you will be able to approve a request by email, by directly clicking on the ‘approve’ button. You can also go to the approval and have more information about it, by clicking on the ‘go to approval’ link.

After clicking on the “Approve” button, you will be redirected to this success page.

Approval from User Portal

To approve an approval request from User Portal, you have to go to users menu and click on “My Approvals”.

After that you will have access to all approvals grid, that are assigned to you. You will be able to approve or reject all the approvals that have waiting status.

After clicking on an approval row on the grid, you will be redirected to approval formtemplate. You can approve or reject the request by clicking on the top right buttons.

After finishing the approval process, you will only be allowed to add notes to the approval and not change its status.

Note: Approvals are only available to empowered users. For more information, refer to the dedicated article here.

Backend Approval Structure

In this article we are going to explain the structure of the approval request for a Backend User.

After opening your Deepser Backend portal, by clicking at “Approvals” module

and the following screen will open:

The Approval structure contains fields that express:

NameDescriptionNote
Model Aliasrepresent the model from which the approval process starsIn our example, your supervisor has created a ticket (or Operation) from which an approval process started.
Titlerepresents the name of our approval processthis field can be editable by Backend User.
Due Daterepresent the expiration date during which the approval process must be approved or refusedthis field can be editable by Backend User.
Statusrepresents the condition of the approval process 

Inside the “Approval items” section is shown a grid with the Backend user responsible for accept or refuse the approval workflows.

Inside the “Related Model Form” section is shown the recap of the Operation or “ticket” that has triggered the approval process.

Therefore, the Backend User can read the Title, the Category, the Status, the Assigned Group and the Description of the ticket related to the approval process.

Note: only “Description” field can be editable by Backend User inside the “Related Model Form” section.

The Backend User can also edit the Form Template of the ticket and can see how the Execution of the Approval process it’s running, by clicking on button, as shown below, located at the top left of the “Related Model Form”.

After doing that, the Backend User can simply Approve or Reject the approval process, respectively with the Green or Red Button located at the top right.

In the next article we are going to explain how to create a workflow process.

Workflow Actions

By definition, an action is a way, technique, or process of or for doing something.

In order to create a workflow process, preconfigured recurring actions can be helpful.

In this course we will cover how to use actions into the Flow module inside Deepser.

Lookup Record

If you want to get a record inside a Deepser model or entity in your workflow process, all you need is the action “Lookup Record” inside your workflow.

After opening your workflow process inside the “Flow” module, to add the action “Lookup Record” inside the FLOW section:

Then the following screen will open:

In our example, we want to get the record of the user that has created the ticket.

We choose the model “DeepAdmin – User” to get the entity of the user and then we set the expression or condition to filter the query.

In our case, we want to get the username equal to the Requester user of the ticket, from the trigger event.

Create Record

If you want to create a record in your workflow process, all you need is the action “Create Record” inside your workflow.

After opening your workflow process inside the “Flow” module, to add the action “Create Record” inside the FLOW section:

Then the following screen will open:

In our example, we choose the model “DeepService – Operation” because we want to create a new Operation (or ticket).

Inside the expression we set the “Type” field equal to the Service Type “Change” and we set the “Status” field equal to “New”.

In our case, the final outcome will be the creation of a new Change request with some precompiled fields.

All the variables were dragged and dropped from the right section inside the trigger variables.

For example, the “Title” and the “Requester User” of the new change were taken from the Operation that has triggered the process.

Update Record

If you want to update a record in your workflow process, all you need is the action “Update Record” inside your workflow.

After opening your workflow process inside the “Flow” module, to add the action “Update Record” inside the FLOW section:

Then the following screen will open:

For example, before the approval process ends, you want to update the status inside your ticket or Operation and set it as “Approved”.

In our example, we choose the model Operation in which we want to update the record (dragged and dropped from the right section inside the trigger variables).

In the Expression section we set the field “Status” equal to “Approved”.

Script Block

In this article we are going to analyse the usage of the “Script” block.

The “Script” block is located in the menu: Action, to access it you will also need to click on the search bar that will appear:

Script is used for more advanced calculations, that cannot be achieved through the default actions.

Script Input

On the input sections you can set all the inputs that are part of the flow and will be used on the calculations in the script. You can add a new input by clicking on the “+” button or delete an input by clicking on the “-” button.

Name: On this field you can set the name of the input value, this name will be later used inside the script.

Type: On this field you can select the type which has to be accurate to the input type, in this case we have an operation collection input.

Value: On this field you can set the value of the input. The value can be set manually, or it can be dragged and dropped from the right side of the flow variables.

Expression (Script)

In the expression section, you can write all the custom code needed for the calculations, by using the set inputs. In this example by using script block, we can calculate and retrieve tickets that have due date in a week. So, retrieved tickets could be used in a flow to be modified or to perform further calculation using default actions (such as Update Record, Lookup Record and so on).

				
					// retrieve the subscription collection (from input)
$operationCollection = $this->getInput('operation_collection');
// retrieve the current date and the current day
$currentDate = new DateTime('now');
$currentDate->setTimezone(new DateTimeZone('UTC'));
$day = $currentDate->format('l');

// calculate the starting day of next week
$nextWeek = new DateTime('now');
$nextWeek->setTimezone(new DateTimeZone('UTC'));
$nextWeek->setTimestamp(strtotime("-1 day +1 week"));
$nextWeek->setTime(0,0);
$nextWeek = $nextWeek->format('Y-m-d H:i:s');

// calculate the ending day of next week
$endOfDay = new DateTime('now');
$endOfDay->setTimezone(new DateTimeZone('UTC'));
$endOfDay->setTimestamp(strtotime("+1 week"));
$endOfDay->setTime(0,0);
$endOfDay = $endOfDay->format('Y-m-d H:i:s');

//filter the operation collection based on the next week day interval
$operationCollection
    ->addFieldToFilter('due_date',['gteq' => $nextWeek])
    ->addFieldToFilter('due_date',['lt' => $endOfDay]);


// Set outputs with the result tickets
$this->setOutput('operations',$operationCollection);
$this->setOutput('operations_count',$operationCollection->count());

				
			

Script Output

All the outputs that are set on the expression area should be also set on the “Output” section. You can add a new output by clicking on the ”+” button or delete an output by using the “-” button.

Label: On this field you can set the label for this output variable, this label will also be visible on the right side of the flow.

Name: On this field you can set the name of the variable, this name should correspond to the name that is set for this variable on the expression script.

Type: On this field you must set the output type that is returned.

After saving the script block, the set outputs will appear on the right side of the flow and be ready to use. The outputs can be found under the “Script” label.

A complete example of script block-based flow can be found here.

Send Email

If you want to send an email inside your workflow process, all you need is the action “Send Email” inside your workflow.

After opening your workflow process inside the “Flow” module, to add the action “Send Email” inside the FLOW section:

Then the following screen will open:

For example, we want to send a message to the Assigned User of the ticket to tell him about the approved request.

Inside each field we set

NameValueNote
ModelDeepServiceOperationWe set this model to take some variables that we need to send by email
FromOutWe set the Outgoing mailbox
To(Variables)Assigned To (from DeepServiceOperation)We want to send an email to the Assigned User of our Operation
SubjectChange Id #(entityId) ApprovedWe set the Subject of our mail including the ID of the ticket

Inside the “Input” section we are going to set the Name of the variable, the Type of the Deepser model or entity and the Value of the Deepser model or entity that we want to use to create our body Html message.

Inside the “Body Html” section we are going to create our message that we want to show to the receiver.

Ask For Approval

If you want to create an Accept/Refuse request to the approval user/group inside your approval workflow and you want to send it into the Deepser portal or to send it by email, all you need is the action “Ask For Approval” inside your workflow.

After opening your workflow process inside the “Flow” module, to add the action “Ask For Approval” inside the FLOW section:

Then the following screen will open:

For example, we want to ask to a group of people to approve a service request, opened by some user.

In our example, we choose the model Operation or “ticket” in which we want to take some variables (dragged and dropped from the right section inside the trigger variables).

In the “Title” section we can write some text and show some variables from the ticket.

In our case, we take the Title and the Requester User related to the ticket from the trigger section.

In the “Approve Rule” section we can choose how the approval process can be approved and we choose to send the request to the Assigned Group assigned to the ticket (or Operation).

Inside the query builder we can find some options:

NameDescription
anyone approvesany user or group chosen can approve the request
all users approveall users chosen need to approve the request
all responded and anyone approves 
% of users approvethe chosen percentage of users need to approve the request
# of users approvethe chosen number of users need to approve the request

In the “Reject Rule” section we can choose how the approval process can be refused and we choose to send the request to the Assigned Group assigned to the ticket (Operation).

Inside the query builder we can find some options:

NameDescription
anyone rejectsany user or group chosen can reject the request
all users rejectall users chosen need to reject the request
all responded and anyone rejects 
% of users rejectthe chosen percentage of users need to reject the request
# of users rejectthe chosen number of users need to reject the request

This configuration allows you to send the request through the Deepser portal.

If you want to send it by email, you need to enable the flag “Enable Email Approval”.

Log Action

If you want to display a message inside your workflow, all you need is the action “Log” inside your workflow.

After opening your workflow process inside the “Flow” module, to add the action “Log” inside the FLOW section:

Then the following screen will open:

For example, inside our workflow we want to display the message:

“The status of the ticket with #ID was not modified”

In our example, we choose the Model Operation to get the entity ID of the ticket (variable dragged and dropped from the right section) and write some text to show our message.

This message will be visible after the execution of the workflow inside the “Execution” tab across the log section. The log file can be also downloaded.

Note: Logs will be visibile only if the flag “Enable Log” inside the Flow Properties is enabled (see article)

Stage Action

If you have divided your workflow into several steps with the module “Stage Set” and you want to add into your workflow the steps that you have created, all you need is the action “Stage” inside your workflow.

After opening your workflow process inside the “Flow” module, to add the action “Stage” inside the FLOW section:

Then the following screen will open:

The final outcome will be:

Stage Error

If you have divided your workflow into several steps with the module “Stage Set” and you want to add into your workflow another step where you want to display an error stage, all you need is the action “Stage Error” inside your workflow.

After opening your workflow process inside the “Flow” module, to add the action “Stage Error” inside the FLOW section:

Then the following screen will open:

The final outcome will be displayed as a “Stage Error” handler.

Workflow Logic

Logical blocks in deepser workflows are very important as they allow the flow of code execution to be redirected.
In this lesson we are going to deal with Logical Blocks in Deepser Workflows.

IF Conditional Block

In this article we are going to analyze the behavior of the conditional block “IF”.

The conditional block “IF” is part of the flow control instructions as it allows to direct the flow towards the execution of some blocks or others based on the veracity of the condition that characterizes it.

The “IF” block is located in the menu: Logic, to access it you will also need to click on the search bar that will appear:

The “IF” block visually will have 2 branches: the left ramo or the branch that will be executed if the condition is evaluated false, this branch is to be considered the continuation of the execution of the flow, and the right branch that will be executed if the condition is evaluated as true.

Note: If an else block is not indicated in the left ramp or an “End Flow” block is not specified in the right branch after the last instruction the flow will first execute the right branch and then the left branch.

EXAMPLE OF CONFIGURATION OF THE “IF” BLOCK

Suppose that when creating an operation we want to assign a specific mailbox if the type of service is “Incident”.

The “IF” block will then be configured as follows:

And the flow will then turn out to be:

Now in the right branch we are going to insert a block “Update Record” configured as follows:

The flow will eventually turn out to look like this:

Once this flow is activated we will see that the new “Incident” Operations will have as a mailbox box the one defined in the flow.

ELSE Conditional Block

In this article we are going to analyze the behavior of the conditional block “ELSE”.

The conditional block “ELSE” is part of the flow control instructions as it allows you to direct the flow towards the execution of some blocks or others based on the veracity of the condition that characterizes the Associated “IF” block.

It goes into fact said that the block “ELSE” to be used needs an associated block “IF”.

The ELSE block is located in the menu: “Logic”, to access it you will also need to click on the search bar that will appear:

The “ELSE” block visually will have 2 branches: the left branch that is to be considered the continuation of the execution of the flow, and the right branch that will be executed if the condition of the associated “IF” block is evaluated as false.

Note: If an “End Flow” block is not indicated in the right branch after the last instruction, the flow will first execute the right branch and then the left branch.

EXAMPLE OF CONFIGURATION OF THE “ELSE IF” BLOCK

Suppose you want to create a flow that when a new operation is created, automatically assigns the priority, assigning high priority if the urgency is high, otherwise you automatically assign medium priority.

To do this we will have to add an “If” block configured as follows:

Now in the right branch we are going to insert a block “Update Record” configured as follows:

In the left branch we are going to insert a “ELSE” block and in its right branch we will insert an “Update Record” block configured as follows:

The flow at the end will turn out to be as follows:

ELSE IF Conditional Block

In this article we are going to analyze the behavior of the conditional block “ELSE”.

The conditional block “ELSE IF” is part of the flow control instructions as it allows you to direct the flow towards the execution of some blocks or others based on the veracity of the condition that characterizes the Associated “IF” block and the condition that characterizes it.

It goes into fact said that the block “ELSE IF” to be used needs an associated block “IF” and can be associated with one or more blocks “ELSE IF” but with a single block “ELSE”.

The block “ELSE IF”, is located in the menu: Logic, to access it will be in addition necessary to click on the search bar that will appear:

The “ELSE IF” block visually will have 2 branches: the left branch that is to be considered the continuation of the execution of the flow, and the right branch that will be executed if the condition of the associated “IF” block is evaluated as false and the condition specified in the “ELSE IF” block is evaluated as true.

Note: If an else block is not indicated in the left ramp or an “End Flow” block is not specified in the right branch after the last instruction the flow will first execute the right branch and then the left branch.

EXAMPLE OF CONFIGURATION OF THE “ELSE IF” BLOCK

Suppose we want to extend the flow we created in the previous article.

Suppose you want to assign the newly created operation low priority in case the urgency is low.

To do this we will have to add a block “ELSE IF” before the ELSE block, to do this we will have to position ourselves on top of the else block and click the “+” symbol that will appear:

Once clicked we will have to enter from the “Logic” menu an element “ELSE IF” configured as follows:

In the right branch of the block “ELSE IF” go to insert a block “Update Record”, with the following configuration:

The flow in the end will turn out to be the following:

 FOREACH Block

In this article we are going to analyze the behavior of the “FOREACH” block.

The “FOREACH” block is a block that allows you to iterate on collections of entities in Deepser and perform one or more actions for each entity in the collection.

The block “FOREACH”, is located in the menu: Logic, to access it will be necessary to click on the search bar that will appear:

The “FOREACH” block visually will have 2 branches: the left branch that is to be considered the continuation of the execution of the flow, and the right branch in which you will have to place the actions to be performed for each iteration of the cycle

Note: If you insert an end flow block in the left branch you will get the result of ending the execution of the flow.

EXAMPLE OF CONFIGURATION OF THE “FOREACH” BLOCK

Suppose we want to send an email notification to the user who created a password in the password manager when it is expired, for this example we will consider expired a password whose Expired field (field managed by a system automatism) is set to yes.

To do this we must initially recover the collection of entities of type “DeepPassword – Password” expired, to do so we will have to go to insert a block “Lookup Records” configured in this way:

At this point we can iterate on the password entities by adding below the previous block a “FOREACH” block, in whose right branch we are going to insert a “Send Email” block:

The “FOREACH” block will be configured as follows:

While the “Send Email” block will be configured as follows :

WHILE Block And Assign value to Variable block

WHILE Block

In this article we are going to analyze the behavior of the “WHILE” block.

The “WHILE” block is a block that allows you to iteratively perform operations

The “WHILE” block is located in the menu: Logic, to access it you will also need to click on the search bar that will appear:

The “WHILE” block visually will have 2 branches: the left branch that is to be considered the continuation of the execution of the flow, and the right branch in which you will have to place the actions to be performed for each iteration of the cycle

Note: If you insert an end flow block in the right branch you will get the result of ending the execution of the flow immediately, similar to what would happen with a break statement in classical programming.

Assign value to Variable block

The “Assign value to Variable” block allows you to assign an arbitrary value or the result of processing to a variable.

EXAMPLE WHILE Block Configuration

Suppose you want to create a series of task review tasks to assign to the ticket assignee, one per month for a total of 10 months.

We assume in addition that we want to calculate the date to and save it in a custom field “Two Dates”

To do this you will need to configure the flow trigger as follows:

At this point we will have to add a script block that will allow us to define an iteration variable for the  “WHILE” cycle.

The Script block will be configured as follows:

Now we can go to add from the Logic section the block “WHILE”, which we will configure in this way:

In the right branch we are going to add now a new script block that will take care of performing the increment of the variable and also of calculating the duedate date within which to do the review of the operation.

The script will then be configured like this:

In the “Expression (Script)” field, we are going to enter the following code:

				
					$iterator = $this->getInput('iterator');
$operation = $this->getInput('operation');
 
$expirationDate = new DateTime($operation->getCreatedAt());
$interval = new DateInterval("P{$iterator}M");
$expirationDate->add($interval);
 
$this->setOutput('exp_date',$expirationDate->format('Y-m-d'));
$this->setOutput('iterator2', $iterator+=1);
				
			

Below the previous block we will have to add a “Create Record” block, which we will configure to create a task at each iteration with the variables calculated by the previous script.

For the creation of tasks, the block “Create Record” you can refer to the image below:

Note: If you do not specify the “Model Id” and “Model Alias” fields, the tasks created will not be displayed in the ticket.

As a last block we will have to insert a block “Assign Value to Variable” configured as segune:

Now the final result will be as follows:

TRY – CATCH End Flow

CONSTRUCT TRY – CATCH

The try-catch construct is a block that allows you to capture the exceptions that can be generated by the various blocks of Deepser flows.

It consists of two blocks respectively the Try block and the catch block.

In the right branch of the try block you will have to insert the blocks of which we want to capture any exceptions, in the left branch a Catch block will be placed, which in turn will perform the actions placed in its right branch if and only if an exception will be generated in the try block.

EXAMPLE OF CONFIGURATION OF THE “TRY – CATCH” BLOCK

Suppose you want to run a script that might throw an exception during its execution, and you want to log in a custom error message if an exception is raised.

To do this we are going to insert a try block in whose right branch we are going to insert a “Script” block, in which we are going to insert the following code:

				
					$operationCollection = Deep::getResourceModel('deep_service/operation');
 
$operationMap = $operationCollection->toOptionHash();
 
//.... rest of the code
				
			

Note: In our example we are going to deliberately insert a block of code that contains an errorn so that we can test the TRY-CATCH construct in particular the alias to get the Operation collection is “deep_service/operation_collection” and not “deep_service/operation”, which is the alias to retrieve a single operation.

Then the script block will be configured like this:

In the left branch of the try block we are going to insert a “Catch” block which in turn will have a desta branch in which we are going to insert our custom logging function.

In particular, in the right branch of the catch block we are going to insert a “Log” block configured as follows:

Below the “Log” block We will have to go and insert an “End Flow” block, in the specific case it can be avoided since there are no other actions to be performed, but in a more general case it may be sensible to exit the flow in case an exception occurs.

At this point the result will look like this:

Block Assign Value to Outputs

The Assign Value to Outputs block is a block that can only be used in subflows to set the value of an output.

When inserted in a Sub Flow, where there is at least one output, the block will be rendered as follows:

If the block is used a flow will be displayed as follows:

Example of “Assign Value to Outputs” Block configuration

Suppose you want to create a subflow that takes care of incrementing an integer variable passed in input to the subflow itself.

To do this we are going to create a new Sub flow whose “INPUTS & OUTPUTS” section will be configured as follows:

Now Let’s add a “Script” block configured as imagined here:

In the “Expression (Script)” section we will then insert the following code:

				
					$input = $this->getInput('input');
$increase = $this->getInput('increase');
 
$this->setOutput('output',$input+$increase
				
			

After the script block, We will have to go to include the block “Assign Value to Outputs” and we will configure it to set in the output “output” the value increased by the script:

Finally we will have to activate the SubFlow to make it available to flows.

Workflow Samples

Configuring a Sample Flow

In this article we are going to see the configuration of a simple flow that will automatically set the high priority when the requesting company is “Acme International”.

Below is the final structure of the flow:

To do this you will need to go to the Flow à Designer menu.

Now you will need to click the NEW button in the upper left corner of the page:

And then on the word “Flow” that will appear below the button

At this point the following page will open:

Below are the fields with their meaning:

  • Name, in this field we are going to define the name that this flow will have.
  • Description, in this field we are going to define the description that will have the flow
  • Icon, in this field we are going to define the icon that will have the flow
  • Enable Log, this toggle if set to you will enable the log in the flow.

Once you have configured the fields mentioned above you will need to click on the “Save” button.

Now the following screen will appear:

At this point we are going to configure the “Trigger” field as follows:

Now you will need to click on “Save” to save the block.

At this point we will have to go and click on the button:

At this point from the menu that will open we will select “Action“.

Once you click in the search bar that will open you will need to click on “Core” à “Update – Record“.

Now from the right bar we have to drag the variable “(Model) DeepService – Operation” in the “Model” section just appeared:

Finally, we must configure the “Expression” field as follows:

Finally, we will have to click the Save button to save the block.

Before enabling the flow, you will need to click on the button:

Placed in below the newly created block, and select from the “Logic” section the “End Flow” block.

After doing so you will need to click Save to save the block.

Before you can see the effects of the flow you will need to enable the flow by setting the toggle “Status“

At this point the flow will be up and running.

Configuring a Sample Flow with the Script block

In this article we are going to see the configuration of a flow that when creating a user or updating it will take care of making an A.P.I. call to retrieve the user’s age from an external service.

For this example we will use the public bees of “agify.io” to recover a fictitious age for the users  that we are going to create given their Nome, in addition we assume that a custom text type field named “Age” on the user model is configured in the Deepser installation.

In this guide we are going to configure in addition to the script action to make the call, a more in-depth guide on this action is available at the following link.

Below is the final structure of the flow:

To do this you will need to go to the Flow -> Designer menu.

Now you will need to click the NEW button in the upper left corner of the page:

And then on the word “Flow” that will appear below the button

At this point the following page will open:

Below are the fields with their meaning:

  • Name, In this field we are going to define the name that this flow will have.
  • Description, In this field we are going to define the description that will have the flow
  • Icon, in this field we are going to define the icon that will have the flow
  • Enable Log, this toggle if set to you will enable the log in the flow.

Once you have configured the fields mentioned above you will need to click on the “Save” button.

Now the following screen will appear:

At this point we are going to configure the “Trigger” field as follows:

Now you will need to click on “Save” to save the block.

At this point we will have to go and click on the button:

At this point from the meni that there is will open we will select “Action”.

Once you click in the search bar that will open you will need to click on “Core” -> “Script”.

At this point we will have to go to add an input “firstname”, which will be enhanced with the firstname of the user we have created, to do this we must drag in the Value field of the input the Firstname field

At this point We will have to go to create an output of the “User Age” script, the configuration of the final field will look like this:

Note: The Name field must match what you set in the scripting section of the document.

In the “Script” field we are going to enter the following code:

				
					//getting the firstname of the user
$firstname = $this->getInput('firstname') ?? "";
 
//inizializing client http
$client = new GuzzleHttp\Client();
 
try{
//making the api call
$res = $client->request('GET', 'https://api.agify.io/', [
'query'=>[
'name'=> $firstname
]
]);
 
//decoding body
$body = json_decode($res->getBody());
 
//if there is an error throw it
if($body->error){
throw new Exception($body->error);
}
//if no age throw an error
if(!$body->age){
throw new Exception('invalid Age');
}
 
//setting the output of the script
$this->setOutput('userAge', $body->age);
 
}catch(Exception $e){
//In case of exceptions log the exceptions
Deep::log($e, null, "agify.errors.log");
}
				
			

At the end of the configuration of the “Script” block, we can click on “Save”.

Now we must add an “Update Record” block from the actions menu on the same branch as the previous one, which will be configured as follows:

As the last step for this block you will need to click on the “Save” button to save the block.

Before enabling the flow you will need to click on the button:

Placed in below the newly created block, and select from the “Logic” section the “End Flow” block.

After doing so you will need to click on “Save” to save the block.

Before you can see the effects of the flow you will need to enable the flow by setting the toggle “Status”

At this point the flow will be up and running

Single Stage Flow

In this article we are going to see the flow configuration that will take care of creating an approval of resource access in the event that an “Access Management” type ticket is opened.

Below we will report the final result of the flow:

To do this you will need to go to the Flow à Designer menu.

Now you will need to click the NEW button in the upper left corner of the page:

And then on the word “Flow” that will appear below the button

At this point the following page will open:

Below are the fields with their meaning:

  • Name, in this field we are going to define the name that this flow will have.
  • Description, in this field we are going to define the description that will have the flow
  • Icon, in this field we are going to define the icon that will have the flow
  • Enable Log, this toggle if set to you will enable the log in the flow.

Once you have configured the fields mentioned above you will need to click on the “Save” button.

Now the following screen will appear:

At this point we are going to configure the “Trigger” field as follows:

Now you will need to click on “Save” to save the block.

At this point we will have to go and click on the button:

At this point from the meni that there is will open we will select “Logic“.

Once you click in the search bar that will open you will need to click on “If“, which will be configured as follows:

In the left branch we are going to insert an “End Flow” block, in the right one we will have to insert a “Ask for Approval” block, from the “Actions” section.

At this point we are going to configure the “Ask for Approval” field in this way:

Below the newly created block we will create an if, in which we will check the status of the approval.

In the left branch of the “If” block we are going to configure an “Else” block, which will be present in the “Logic” section.

In the right branch of the IF we are going to add an “Update Record” block, which will be configured as follows:

In the right branch of the “Else” branch we will instead add an “Update Record” block, which will be configured as follows:

On all terminal branches of the flow, it will be necessary to insert an “End flow” block.

Before you can see the effects of the flow you will need to enable the flow by setting the toggle “Status“

At this point the flow will be up and running.

Multi Stage Flow

In this article we are going to see the flow configuration that will take care of creating a resource access approval in the event that an “Access Management” type ticket is opened.

For this tutorial, suppose that the environment has a type of “Access Management” service, already configured.

Suppose that this flow requires 2 stages of approval: in the first phase it will be up to the assignee group of the ticket to authorize access to the resource, in the second phase it will be a Deepser administrator user to authorize access to the resource.

STAGE CONFIGURATION

The internships that we are going to create will be the following:

  • Approval Of assignee Group
  • User Administrator Approval
  • Approved
  • NotApproved

To configure a Stage Set it will be necessary to go to the Flow à Stage Set menu.

At this point we must click on the “Add Stage Set” button, then we will have to set in the Name field “Approvation Stage Set” and then click on “Save” or “Apply“.

At this point it will be possible to include in this stage set just created the various stages necessary, to do so you will need to click on Add Template:

Now in the screen that will open it will be possible to configure the new stage, for the purposes of this guide we can only configure the “Name” field and click on the “Save And New” button.

We will have to repeat this step for each stage we want to add.

For more information about stage sets and internships, please consult the page dedicated to Stage Sets by clicking on this link.

Once you have finished adding the stages we can go and click on the “X” button located in the upper right corner of the screen.

CONFIGURING A FLOW WITH MULTIPLE STAGES

Below we will report the final result of the flow:

To do this you will need to go to the Flow à Designer menu.

Now you will need to click the NEW button in the upper left corner of the page:

And then on the word “Flow” that will appear below the button.

At this point the following page will open:

Below are the fields with their meaning:

  • Name, in this field we are going to define the name that this flow will have.
  • Description, in this field we are going to define the description that will have the flow
  • Icon, in this field we are going to define the icon that will have the flow
  • Enable Log, this toggle if set to you will enable the log in the flow.

Once you have configured the fields mentioned above you will need to click on the “Save” button.

Now the following screen will appear:

At this point we are going to configure the “Trigger” field as follows:

Now you will need to click on “Save” to save the block.

Before continuing the configuration of the flow, it will be necessary to import the stages created in the previous point of this guide, to do so we will have to click on the three dots placed in the upper right part of the page.

In the screen that will open you will need to select from the drop-down menu the Stage Set to import and click on “Import“.

At this point, the stages set in the previous step of this guide will appear.

After clicking on the “Save” button, the stages will have been imported correctly.

At this point we will have to go and click on the button:

From the “Actions” section we are going to select a stage block that we will configure as follows:

ASSIGNEE GROUP APPROVAL

At this point in the article, we are going to make a first big distinction that is, we will differentiate the case in which there is an assignee group in the ticket and the case in which there is not.

Next, we will have to insert an “If” block from the “Logic” section below the previous block, the if block will be configured in the following way to verify that the assignee group is set in the ticket.

CHECK IF THE ASSIGNEE GROUP IS NOT PRESENT

In the left branch of the “IF” block we are going to configure an “Else” block, which will be present in the “Logic” section.

In the left branch we are going to insert an “End Flow” block.

CHECK IF THE ASSIGNEE GROUP IS PRESENT

In the left branch we will insert a “Stage Error” block and an “End Flow” block, in the right one we will have to insert an “Ask for Approval” block, from the “Actions” section.

At this point we are going to configure the “Ask for Approval” block like this:

CHECK FIRST APPROVAL

At this point of the flow, we will insert an if block that will check if the approval has been accepted or if it has been rejected.

The if block will be configured as follows:

Below this IF we will have to go to configure in the left branch an Else block and in the right one instead, we will configure the procedure to continue the approval, as discussed in the following points of this article.

ELSE BRANCH CONFIGURATION:

In the left branch of the “if” block we will instead add an “Else” block, we will then insert a Stage block that will be configured in the following way:

Below the previous block we are going to insert an update record:

After this block, remember to insert an End Flow block.

IF BRANCH CONFIGURATION:

In the right branch of the “IF” block we will instead add a “Stage” block, which will be configured as follows:

Below the block a previous we are going to insert Script block that we will configure as follows:

In the “Expression (Script)” section we will insert the following code:

				
					$usersCollection = Deep::getResourceModel('deep_admin/user_collection');
$usersCollection->getSelect()->join('admin_role', 'main_table.user_id = admin_role.user_id', [])
                             ->join(['ar2' => 'admin_role'], 'ar2.role_id = admin_role.parent_id', array('user_type'));
 
$usersCollection->addFilterToMap('user_id', 'main_table.user_id');
$usersCollection->addFieldToFilter('ar2.user_type', ['eq'=> 'ADMIN']);
$this->setOutput('administrators', $usersCollection);
				
			

After the scripting block we must go to insert a new approval, through a “Ask for Approval” block, which will be configured as follows:

CHECK SECOND APPROVAL STATUS

At this point we will have to go to configure an if block that will allow us to check in which state the approval is.

To do this we will have to add under the previous block “Ask for Approval” a block “if” configured in the following way:

Below this if we will have to include in the right branch the case in which the approval was successful and in the left branch the case in which it was rejected.

APPROVED ACCEPTED BRANCH CONFIGURATION

In the right branch we are going to figure a block “Stage” configured as follows:

Then we will insert a block “Update Record” which will take care of changing the status of the ticket that gave rise to the flow, to do this we will insert the following configuration in the update record block:

As a graphic precaution for users in this flow it was decided to set the “Error” status on the “Not approved” stage in case of approval.

To do this you will need to Add a Stage block configured as follows:

And then insert a “Stage Error” block, which does not require configurations.

CONFIGURATION BRANCH APPROVAL REJECTED

In the left branch of the if block that controls the second approval, we are going to insert a Stage block configured as follows:

And finally, an “Update record” block to change the status of the ticket on which the flow is being executed:

Before you can see the effects of the flow you will need to enable the flow by setting the toggle “Status”.

At this point, the flow will be up and running.

SubFlow

SubFlows are flows which have the purpose of performing common operations between several flows, and can also be seen as functions which can be called across flows.

Configuring a sub flow

Sub flows in Deepser can be seen as functions that can be called up in various flows to perform common operations between the various flows.

In this article we are going to configure a Sub Flow that will take care of changing the status of the operation associated with an activity.

Configuring the
subflowTo do this you will need to go to the Flow -> Designer menu.

Now you will need to click the NEW button in the upper left corner of the page:

And then on the word “Sub Flow” that will appear below the button

At this point the following page will open:

Below are the fields with their meaning:

  • Name, in this field we are going to define the name that this flow will have.
  • Description, in this field we are going to define the description that will have the flow
  • Icon, in this field we are going to define the icon that will have the flow
  • Enable Log, this toggle if set to you will enable the log in the flow.

Once you have configured the fields mentioned above you will need to click on the “Save” button.

Now the following screen will appear:

In the “INPUTS & OUTPUTS” block we will configure the inputs and autput of the function.

In our case the block “INPUTS & OUTPUTS”, will be configured as follows:

Once you have configured this block you will need to configure a “Lookup Record” block that we will configure as follows:

Below the previous block we must insert a “Script” block with the following configuration:

The script will take in input the operation retrieved from the lookup records block and the new state, provided to the invocation of the SubFlow and will provide in output an integer that will be worth zero if the update operation was not successful and 1 if the status of the operation has been changed.

In the Espression (Script) field we will have to enter the following code:

				
					$operation = $this->getInput('operation');
$status = $this->getInput('status');
if($status && $operation && $operation->getId()){
    $operation->setStatus($status);
    $operation->save();
    $this->setOutput('done', 1);
}else{
    $this->setOutput('done', 0);
}
				
			

Finally we will have to add a block “Assign Values To Output” present in the “Logic” section, configured as follows:

Finally, to finish the SubFlow you will need to enter an “EndFlow” block.

Before you can use the  newly created subflow you will need to enable the sub flow by setting the “Status” toggle as follows:

At this point the sub flow will be up and running

Using a sub flow

In our example we are going to create a new flow that will be performed when a new activity is created and that will call the newly created sub flow.

To do this you will need to go to the Flow -> Designer menu.

Now you will need to click the NEW button in the upper left corner of the page:

And then on the word “Flow” that will appear below the button

At this point the following page will open:

Below are the fields with their meaning:

·  Name, In this field we are going to define the name that this flow will have.

·  Description, In this field we are going to define the description that will have the flow

·  Icon, in this field we are going to define the icon that will have the flow

·  Enable Log, this toggle if set to you will enable the log in the flow.

Once you have configured the fields mentioned above you will need to click on the “Save” button.

Now the following screen will appear:

At this moment we are going to configure the “Trigger” field as follows:

Now you will need to click on “Save” to save the block.

At this point we will have to go and click on the button:

At this point we will have to click on the “Sub Flow” section, we will have to select the sub flow that we have created:

Which will be configured in the following way:

Under this block we will add an if block that will check if the status of the work has been changed, verifying the return flag, or not.

If the status has not been changed, it will print a message in the flow log to have visibility of the changes.

Before you can see the effects of the flow you will need to enable the flow by setting the toggle “Status”

At this point the flow will be up and running

Inventory

Discover how to manage inventory effortlessly with Deepser’s Inventory Module course. You’ll learn how to handle stock, keep track of items, and allocate assets efficiently. From learning about inventory lifecycles to ensuring optimal stock levels, you’ll gain the skills needed to oversee warehouses, monitor product movement, and use smart restocking methods. With mastery of the Inventory Module, you’ll simplify operations and enhance overall efficiency within your organization.

Inventory Overview

The “Inventory” section of Deepser is made up of 3 different modules related to each other:

  1. Warehouse
    Warehouse entity is used to add all the information related to the locations of products storage and stock. 
  2. Item
    On the Item entity you can manage the items related to the warehouse entity.
  3. Movement
    With the Movement entity, you can manage all item movements with actions such as: load, unload, or relocation

The joint use of these three modules allows you to manage and track items. In particular, it allows you to:

– Monitor the available quantity of each inventory item

– Register new articles

– Track loading, unloading or transfer movements between warehouses

Inventory Configuration

The module was created to allow the configuration and management of different warehouse types. 

 

The configuration of these types is the responsibility of an administrator user. In fact, via SYSTEM > INVENTORY CONFIGURATION it is possible to access the dedicated area for the configuration of new typologies. 

Below is the list of available fields and their meaning: 

Field 

Description 

Name 

This field identifies the warehouse name. This will also be displayed in the warehouse access menu on the left. 

Position 

Indicates the display position of the item within the Deepser access menu 

Description 

Descriptive field  

Icon 

Through this field it is possible to associate an icon with the type of warehouse 

Groups 

Identify which groups have access to the warehouse type from the backend 

Portal Groups 

Identify which groups have access to the warehouse type from end-user portal 

Groups Menu Visibility 

By specifying one or more groups in this field, you allow them the possibility of viewing the warehouse type item in the Deepser menu. 

Frontend visibility 

It allows visibility of the warehouse type from Frontend. 

State 

Using this field, you can enable or disable the warehouse type. 

Incremental Prefix 

Using this field, you can configure a prefix to be applied in warehouse numbering. (It is used to enhance the Incremental ID field present in the warehouse main data). 

Incremental Suffix 

Using this field, you can configure a suffix to be applied in the warehouse numbering. (It is used to enhance the Incremental ID field present in the warehouse main data). 

Incremental ID 

Using this field, you can configure an ID to be applied in the warehouse numbering. (It is used to enhance the Incremental ID field present in the warehouse main data). 

Incremental Padding Font 

Using this field, you can configure a padding character to be applied in the warehouse numbering. (It is used to enhance the Incremental ID field present in the warehouse main data). 

Incremental Padding Length 

Using this field, you can configure the length of the padding to be applied in the warehouse numbering. (It is used to enhance the Incremental ID field present in the warehouse main data). 

Warehouse

Once the warehouse type has been created, you can proceed with the creation of the Warehouse entity directly from the INVENTORY > WAREHOUSE menu: 

The “Warehouse” module constitutes the fundamental link between the “Item” and “Movement” modules, guaranteeing accurate and updated management of goods stocks and transactions. 

Below is the list of available fields and their meaning on the warehouse entity:

Field 

Description 

Name 

Warehouse name 

Model Alias 

Select field where you can choose a model from Deepser that is connected to this warehouse. 

Model Id 

Text field where you can choose an Id of a record from the selected model in the above field. 

Address 

Through this field it is possible to associate an address with the warehouse. Using the “+” icon it will be possible to create a new address that can be associated with the warehouse. 

Type 

Select field with the warehouse type 

Increment Id 

The field in question will be auto-valued based on the configuration of the specific automatic numbering fields present in the typology configuration. 

Is default 

Checkbox that differentiates the main default warehouse from others. At least one warehouse should be default. 

Status 

Using this field you can enable or disable the warehouse and its use within any connected modules. 

Into this entity are also present the following structured fields: 

Items – grid 

Grid field that shows all the items connected to this warehouse. You can also add an item directly from the warehouse by clicking on the “add Item” button at the right corner. 

 

Within this grid it is also possible to move the quantities of the individual warehouse item in a guided manner using the icons in the “Actions” column.

The available icons are as follows:

  • “+” allows you to load a quantity of the product
  • “-” allows you to unload the product
  • The transfer icon, on the other hand, allows you to transfer a quantity of a product from one warehouse to another.

Movements – grid

Grid field that shows all the movements connected to this warehouse and the items connected to it. You can also add a movement directly from the warehouse by clicking on the “add Movement” button at the right corner. All the movements that are added on this warehouse form should be about one of the items connected to it.

Item

On the Item entity you can create different items, connect them to specific warehouses and create movements linked to them.

Below is the list of available fields and their meaning on the Item entity:  

Field

Description

Warehouse

Select field that is used to link this item to a warehouse.

Serial Number

Text field where you can add a serial number for this item

Quantity

Text field that is used to set a quantity for this item. This refers to the current available quantity of a specific item in your inventory.

Description

Text field where you can set a name or description to your item

Minimum Quantity

Text field to set the minimum quantity ,which is the threshold level below which you do not want your item quantity to fall.

Note

Textarea field that is used to set notes for this item.

Movements

Grid field that shows all the movements related to this item. By clicking on the “Add movement” button you can directly create a movement for this item.

Another way to quickly create movements for an item is by using these 3 buttons on the items grid.

  • The “+” button is used to add a movement of type load.
  • The “-” button is used to add a movement of type unload.
  • The arrows button is used to add a movement of type relocation.

Movement

Movement entity is used to manage all the item movements with actions like: load, unload or relocation. This model helps to keep track of all quantity management of items and relocation of them from one warehouse to another.

Below is the list of available fields and their meaning on the movement entity:  

Field

Description

Quantity

Text field that is used to set the quantity from the item that you want to load, unload or transfer.

Date

Datetime field that is used to set a date for the movement.

Type Code

Select field with two options: load and unload. When you load an item the quantity of it is added with the quantity set on the movement and the other way around goes for unload.

Is Relocation

Checkbox field which is used to check if the movement action is relocating the item from one warehouse to another. When Is Relocation is set to “YES”, type code will always be of type unload.

Warehouse

Select field that is used to set the warehouse for this movement.

Item

Select field that is used to set the item for this movement will apply to.

Destination Warehouse

Select field that is used to set the destination warehouse for this movement if “Is Relocation” field is set to “YES”.

Destination Item

Select field that is used to set the destination item for this movement if “Is Relocation” field is set to “YES”. Destination Item should correspond to all items present in “Destination warehouse”.

Note

Textarea field that is used to set notes for this item.

Status

Select field is used to set the status of a movement which can be: confirmed or pending.

Custom Fields

Inside Deepser, the Custom Fields module allows the dynamic creation of additional fields to those present in the system within your database.

Inside the custom fields module there are all the tables within Deepser to allow you to customize, according to your needs, the entities that are part of it.

For example, consider the request for some organizations to insert a text field with the address of a building inside a form.

This additional information may be useful to enter it in order to communicate it to a technician who must carry out an on-site intervention.

Custom Field Overview

To create new custom fields, just go to: System -> CustomFields. Inside there is a grid of all the modules installed in Deepser.

Inside there is a grid of all the modules installed in Deepser. 

In order to view the custom fields of a specific entity, click on the grid row. 

In our example we want to take the ticket table. Inside Deepser, it is the Service module and the Operations entity. 

The Model tab contains the data of the model (or Module / Entity) that we are modifying.

The Fields tab contains all the custom fields created for that model, in addition to the system fields.

So we can see all the user-defined fields that are not part of the Deepser system fields. 

In the next article we are going to configure a new custom field. 

Custom Field - Creation

Custom field is a module located in System > Custom Fields [1] and is used to create new fields inside each available model. You can see the grid with all the models in your environment and you can filter them by name and model alias. 

Model  

When you click a model, the following window will open. This window contains the model details [1] and on the left side is the menu for the model. The model details are the model alias, model name and the status of this model. On the menu [2] you have: 

  • Model – current model information, currently selected. 
  • Fields – where you can create new fields and edit the previous created ones. 
  • Events – here you can create new events or edit the created ones. 
  • Table Management – here you can manage the database table directly. 
  • Import/Export – is used to import/export different fields and events from this environment to a new one. 

Fields 

‘Fields’ tab is located below model and is used to create new fields or modify already existing fields. You can filter the existing fields by the tab [1]. The most used filters are: 

  • Defined by user 
  • Label 
  • Column name 

You can create a new custom field by clicking “Add Field” [2] or you can edit the existing ones by clicking the corresponding row, clicking the icon in the “New Tab” column or the icon in “Action” column. 

Add field 

When we click “Add Field” button the following page will appear. On this page you can fill the required data to create a new field on the selected module. These fields can change if we change the value of the element type.  

 

The fields have the following meaning: 

                                                                  SECTION FIELD 

Field 

Description 

Note 

Label 

Name of the field that will appear as its title 

 

Column Type 

Type of column in the database 

At the bottom of the this article it is explained in detail, here is a list: 

-text 

– long text 

-entire 

-decimal 

-date 

– a column must not be created in the DataBase because (for example) it is a display-only field 

Element Type 

It is the type of HTML element displayed on the form Template.  

Several values are possible and the details will be discussed in the next article. 

The most important are: 

–Activity: an element for inserting and viewing Activities will be displayed in the form. 

–Attachment: an element for inserting and viewing Attachments will be displayed in the form. 

–Category: an element for inserting Categories will be displayed in the form. 

–Date / Datetime: an element for inserting Date (or Date / Time) will be displayed in the form. 

–RelationGrid: a grid for the relationships between records will be displayed in the form (see this guide). 

–Select: a select-box will be displayed in the form. 

–Text: a text box will be displayed in the form. 

–TextArea: a text-area box will be displayed on the form. 

Column Name 

Name of the column within the Database 

When created by the user, the prefix “cust_” is added 

Status 

Status of the custom field. 

Use this setting when creating a field, to create it directly in the DB, or create it in the DB at a later time. This is used to set the field in the DB and / or to create it on the DB. 

–Enabled: the field is enabled and created in the DataBase. 

–Disabled: field not active. 

–Pending: the field has just been created and is not yet inserted in the DataBase. 

For example, you can keep it in the “Pending” state and create it only when there is less activity on the DataBase (in order to be able to check the configurations). 

 

 

                                                                     SECTION ADVANCED 

 Field 

 Description                                                                    

Note 

Global Search 

Allows you to search for the field in the global search 

–Yes: adds the field in the global search 

–No: do not add the field in the global search 

Class 

CSS class of the element displayed in the form 

 

After Element HTML 

HTML code that is inserted after the element. 

It is used to override the HTML code of an element. 

For example, if you configure a text-area column with a link to a map, here you can insert the HTML code for viewing the map instead of a text-area 

On Click 

Javascript event triggered by clicking on the element 

 

On Change 

Javascript event triggered when the element is changed 

 

Values 

For the Select fields the list of values, in the form of a PHP array (key – value) 

 

Custom Element Data 

An array retrieved, for example from a custom source to populate the element. 

For example the call to an external REST API that populates a Select with the values retrieved from a list of an external software 

  • Status – is the status of this field, if it will be used or not. 
  • Type Code – is the return type of the field when we use it inside Flow. 

Following the definition of the new custom field, it will be inserted within the fields available in the form template of the module entity.

We have different element types that we can chose from depending on what we are going to store and how we are going to store it.

  • Activity
  • Address
  • Approvalgrid
  • Attachment
  • Category
  • Checkbox
  • Color
  • Cronexpression
  • Date
  • Datetime
  • Deeppassword
  • Editor
  • Emailaddress
  • Emailgrid
  • Emailwriter
  • Grid
  • Rating
  • Relationgraphview
  • Relationgrid
  • Select
  • Signature
  • Inventoryitemgrid
  • Inventorymovementgrid
  • Invocegrid
  • Invocerelatedmodelgrid
  • Kbtips
  • Label
  • List
  • Multiselect
  • Number
  • Password
  • Percentage
  • Price
  • Progressbar
  • Qrcode
  • Radio
  • Radios
  • Task
  • Teamviewer
  • Text
  • Text area

In the next article we are going to explain the element type simple.

Custom Field - Element Type Simple

Attachment

View

Attachment is used to store different files.

The field will be displayed as follows:

Field Configuration

Column Type: Don’t create DB column.

The extra tab changes with the following fields:

Field

Description

Note

Type

File type of the attachment, default equals all types

 

Minimum number of attachment

 

 

Maximum number of attachment

 

where -1 is unlimited

Display mode

Sets the display of the elements inside the form, grid or list.

 

Category

View

Category is used to define the category of the current entity. This field contains various select fields. Each select field is connected to Category model.

If you select one in the first, then you will be prompted another select with children of that selected category as values and so on until the selected category doesn’t have any children. You can add and edit categories in System > Categories. The render on the form will be as follows:

Field Configuration

Column Type: Don’t create DB column.

Checkbox

View

Checkbox is an element type that is rendered in 2 ways inside the form.

                         Checkbox Render

                             Toggle Render

Field Configuration

Column Type: Integer or Text

 When we select this element type, we have new fields in “extra” tab:

Field

Description

Note

Render as Toggle

if the element will be rendered as toggle instead of checkbox inside form

 

Toggle Size

 

 

Toggle Width

 

 

Toggle Height

 

 

Toggle On Color

color of the toggle when it is switched on

 

Toggle Off Color

color of the toggle when is switched off

 

Toggle On Outline Color

color of the outline when toggle is on

 

Toggle Off Outline Color

color of outline when toggle is off

 

Toggle On Label

label of the toggle when it is switched on

 

Toggle Off Label

label of toggle when it is switched off

 

 

Color

View

This field is used to select a specific color and save the value as HEXA, RGBA or HSVA .

The render inside form is as below:

Field Configuration

Column Type: Text

Date and DateTime

View

Date and Datetime formats renders a calendar where you can select the date you wish and in the case of date time below the calendar you have the time inputs.

The rendering for date is:

The render for datetime is:

Field Configuration

Column Type: Date

Editor

View

Editor is a field that is used to store large texts and is associated with a text area column type.

Field Configuration

Column Type: Text Area

When we select this element type, we will see these new fields inside the extra tab:

Field

Description

Note

WYSUWYG (Advanced Editor)

is used to turn the text area field to a mini word document where you can change the design of the text

 

Mentions

is used by the end users to mention someone

 

Quick Replies

is used to write a generic answer. To use quick replies you need to enable advanced editor. To create new quick replies you need to go to System > Quickreply module configuration

 

Browser Spell Check

check for spelling errors

 

These fields are by default set to no

File

View

By selecting the File type, the element, once added to the form, will allow the insertion of a file.

The file will be automatically stored in a dedicated folder, only the path of the file on the server will be stored in the field you are configuring.

Field Configuration

Then select the ‘Text’ option as the ‘Column Type’.

Label

View

Label is the easiest field type. This field is used to display a label or a text. The text that will be displayed is the label of the field.

Field Configuration

Column Type: No DB column

List

View

List is used to create a select field connected to a selected list.

Field Configuration

Column Type: Text (text or alphanumeric key) or Integer (numeric key)

When we select this element type, we can see a new field inside field tab called List Code which connects to the selected list.

All values of the selected list are shown in the select field rendered in the form.

If we go to ‘Extra’ tab we can see 3 new fields:

Field

Description

Note

Placeholder

placeholder shown when we don’t select anything

 

Group Filter

is set to yes this will apply the group filter that each value has set inside list

 

Model Filter

is set to yes this will apply the model filter that each value has set inside list

 

Number

View

Number is an element that is displayed as a number input field where you can type only numbers and without a leading 0. The render is as follows:

Field Configuration

Column Type: Integer

If we go to ‘Extra’ tab we can see only 1 field:

Field

Description

Note

Decimal Precision

indicates the decimals of the number

 

Password

View

Password is a simple input field of type password

Field Configuration

Column Type: Text (password can be alphanumeric).

 

 

Percentage

View

Percentage is an element that is rendered as a number input field that holds decimals with an extra element below it [%] indicating that this field is a percentage.

Field Configuration

Column Type: Decimal

 

 

Price

View

Percentage is an element that is rendered as a number input field that holds decimals with an extra element below it [USD] indicates that this field is a price.

Field Configuration

Column Type: Decimal

You can select the currency on System > Configuration > Currency Setup.

Radio

View

Radio is an input element of type checkbox with a different style.

Field Configuration

Column Type: Integer

 

 

Radios

View

Radios is the complex version of radio element type.

For example, with these configurations we will have all the operations statuses listed as radios and where we can select only one.

With these configurations we will have all the operations statuses listed as radios and where we can select only one.

 

Field Configuration

Column Type: Text or Integer

If we go to ‘Extra’ tab we can see 3 fields:

Field

Description

Note

List Code

indicates the list that will be display

 

Columns

indicates on how many columns these values are going to be distributed

 

Responsive

sets if the element will be responsive to different screen widths

 

Rating

View

Rating is an element displayed as stars and the value of this field is the number of stars selected.

Field Configuration

Column Type: integer

In the ‘Extra’ tab we see a field:

Field

Description

Note

Max Value

max value that indicates the maximum stars that will be displayed

 

Signature

View

This field has 2 main components displayed inside the form:

  • “➕” that is used to create a new one. When clicked it will open a modal where you can draw the new signature.
  • “🚫” is used to empty image holder.

Once the signature is inserted, a small new image will appear. This image contains the signature.

Field Configuration

Column Type: text area.

 

 

Teamviewer

View

This type is used to connect to Teamviewer application. It is rendered as a button and when clicked the teamviewer configuration window will pop up. If already configured, then the Teamviewer app will launch. Beside this button we have the refresh icon that is used to refresh the connection.

Field Configuration

Column Type: Don’t create DB Column

Text and Textarea

View

These types of elements are used to store text.
The render for Text is:
The render for Text Area is:

Field Configuration

Column Type: Text or Text Area (depends on the length of the text)

Custom Field - Element Type Advanced

Activity

View

Activity element is a complex field that is used to create comments and worklog.

Field Configuration

Column Type: Don’t create DB column

If we go to “Extra” tab after selecting the element type, we find the following fields:

Field

Description

Note

Default Grid

Here we can select the default grid that we want to display as the worklog grid.

If we leave it blank, as default, this field will show only worklogs that are related to this model instance

Allowed Types

Models that are allowed to be displayed

 

Address type

View

Address type is a complex field that is used to store physical addresses of entities in sales and inventory module.

The rendering in the form will look like the following image where you can see the addresses related to current model instance and add a new one. You can create a new one by clicking “Add Address”.

When you click Add Address the following window will appear where you can fill the required fields to set a new address related to this entity.

Field Configuration

Column Type: Don’t create DB column

 You can choose the type of the entity related to this address field: Sales or Inventory.

Approvalgrid

View

Approvalgrid is a complex field displayed as grid inside the form of the current model. This type is used to display the approvals related to this entity.

Field Configuration

When we choose this element type the ‘extra’ tab will change to the following fields.

Field

Description

Note

Default Grid

Grid that will be displayed

Here you need to choose only the grids that are DeepApproval model

Sort Column

the column that the sort will be based on

 

Sort Direction

Identify if the sorting will be ascending or descending

 

Disable Row Click

doesn’t allow redirect to the selected entity on element click

 

Placeholder

 

 

Url Parameters

is used to pass other parameters

The form is: name of the field on the first input and the value you want in the second input

Cronexpression

View

Cronexpression is used to generate chronological expressions.

The render for this type is:

Below the field you have a select field where you can select values of never, 5 minutes, 2 hours, minute, hour, day, week, month, year.

 

Field Configuration

Column Type: Text

These types of elements are found inside models that have automatism because it can be used to trigger the automatism on chronological basis.

 

 

Deeppassword

View

Deeppassword is a complex field that is related to DeepPassword module. Here you can create and store passwords. The rendering of this element is:

If you click the “+” button it will prompt, you with a window where you can create a new password. To create a password, you first need to set the passphrase in System > Configuration > Password > System Passphrase.

If you click inside the input field, you will see a list of currently existing passwords.

Field Configuration

Column Type: Don’t create DB column

 

Emailaddress

View

Emailaddress is used to store email addresses.

This is rendered on the form as an input type and when you insert an email and press spacebar or enter it will create a label of that email.

Field Configuration

Column Type: Text or Text Area

When we select this type, we will have a new switch available inside ‘Extra’ tab.

Field

Description

Note

Enable Ajax

when this is on, and we click the field inside the form a dropdown with all users with email address will be available.

If we start typing this list will be filtered by the text we write

 

Emailgrid

View

Email grid is used to display all emails related with this entity. This field will be displayed as a grid will all the emails available.

Field Configuration

Column Type: Don’t create DB column

Emailwriter

View

Emailwriter is an element rendered as a button:

When we click the button, a popup will open where you can write a new email related to this entity. If we write an email here the email will be available inside the emailgrid we explained above.

This is the popup that will be shown when you click the button. You can edit this form to your needs.

Field Configuration

Column Type: Don’t create DB column

Grid

View

Grid element type is used to render a grid inside the form.

Field Configuration

Column Type: Don’t create DB column

 The fields available inside extra tab are:

Field

Description

Note

Route

is used to determine the route of the grid

In the example we see “*/admin_user/grid/” where * stands form hostname +/admin. After that we see the module name _ entity name /grid/

Default grid

select a grid that will be displayed

You need to choose a grid that is the same entity and module as the one defined in the route field

Sort column

the column based on which we will sort the element

 

Sort direction

Ascendent or descendent

 

Disable row click

 

if we set it to no when we click a row inside the grid it will redirect us to the element we clicked.

Placeholder

 

 

Url parameters

 

is used to further filter the elements we want to display on this grid. Inside the first input we write the column name on which we can filter, and the next field holds the value of the filter.

 



Inventoryitemgrid

View

Inventoryitemgrid is only to display grids related to inventory item module. The render is the same we see inside the inventory item.

You can add new item to this grid by clicking “Add Item”.

 

Field Configuration

Column Type: Don’t create DB column

In the ‘Extra’ tab this grid has the same fields as the default one.

The only thing that differs is that the field ‘Default Grid’ should be populated with a grid of type DeepInventory – Item. If not, the default grid inside this inventory item will be displayed.

The route field is missing because it is predefined to be only for the inventory item.

 

Inventorymovementgrid

View

Inventorymovementgrid is only to display grids related to inventory movement module. The render is the same we see inside the inventory movement.

You can add new movement to this grid by clicking “Add Movement”.

 

Field Configuration

Column Type: Don’t create DB column

In the ‘Extra’ tab this grid has the same fields as the default one.

The only thing that differs is that the field ‘Default Grid’ should be populated with a grid of type DeepInventory – Movement. If not, the default grid inside this inventory movement will be displayed.

The “Route” field is missing because it is predefined to be only for the inventory movement.

 

Invoicegrid

View

Invoicegrid is used to display invoices related to this entity. You can add new invoices by clicking “Add Invoice” button.

Field Configuration

Column Type: Don’t create DB column

The ‘Extra’ tab has the same fields as default grid type.

The “Route” field is missing because it is predefined to be only for the invoice. You need to set the field “Default Grid” to a DeepSales – Invoice.

 

 

Invoicerelatedmodelgrid

View

Invoicerelatedmodelgrid is used to display entities related to other entities that are different to the current model. This element type has a ‘Don’t create a DB column’ column type.

For example, this field is used in DeepSalesInvoice to display activities related to the operation that you want to invoice.

If you click the button “Add Activity”, you can insert activities that you want invoice.

Field Configuration

Column Type: Don’t create DB column

The ‘Extra’ tab on the configure field has the same fields as the default grid type, the only thing that differs is the field “Related Model Alias”.

Field

Description

Note

Related Model Alias

 

is the model related to other model different to the current model

Multiselect

View

Multiselect is a field where you can select multiple elements of a predefined array

Field Configuration

Column Type: text or integer.

The elements are written inside the advanced tab in “Values” where you should return an array with key => value as shown below.

This type of element requires the configuration of a custom event to work.

Progressbar

View

This element is shown inside the form as a progressbar.

Field Configuration

Column Type: decimal

We can alter the element by percentage inside the extra tab. We have the level field where the first input is key which holds the level from 0 to 100 and the second input holds the CSS class assigned to the element if the current value is less than or equal to the corresponding percentage.

This type of element requires the configuration of a custom event or a flow to work.

 

Qrcode

View

Qrcode element is used to display a QR code that corresponds to the value assigned.

This element just displays data as a QR code and is not stored in Data Base as a image.

 

Field Configuration

Column Type: text or text area (depending on the size of data that will be stored).

Inside extra tab we find these fields that are used to style this element.

Field

Description

Note

Style width

width of the image rendered

 

Style height

height of the image rendered

 

Style top

number of pixel from the top

 

Style left

number of pixel from left

 

Style position

position of the image

CSS position types applied

Relationgrid

View

Relationgrid displays the relation between 2 entities as a grid.

When we select this element type, another field called ‘relation’ will become visible, containing the relation to which we are referring.

You can add new entities to this relation by clicking “Add” button or you can change the display columns by clicking “Edit” button.

 

Field Configuration

Column Type: don’t create a DB column

Inside the ‘Extra’ tab we have a new field.

Field

Description

Note

Opposite

If this field is ‘yes’, then the relation is the opposite version

 

Select

View

Select type is a selection field.

 Field Configuration

Column Type: integer or text

When we select this type, the extra tab is filled with the following elements:

Field

Description

Note

AJAX Url

the model of the entities that we will show inside the options.

 

AJAX Disable Cache

disable the cache so every time we click on the select field a request is made.

 

Ajax Value Field

the value attribute of each option

 

AJAX Selection Field

the data we want to display inside the option during the selection process.

 

AJAX Result Field

the data we want to display inside the option after we select one and how it will be displayed.

 

Use Model Grid

if set to yes on the right side of the select field will be a button that will open a modal with all filtered elements displayed as grid.

 

AJAX Additional URL Parameters

these are used to add filters to the displayed options

The format of the filters is as follows:

filter[id_of_filter][attribute] – is the column name on which this filter is based on.

filter[id_of_filter][operator] – is the value on which this column will be filtered.

 

Since we can add more than one filter we identify the pairs by the id_of_filter value starting from 0. Most used operators are eq, neq, in.

 

Task

View

Task is a field that is used to keep track of tasks assigned for this entity.

Field Configuration

Column Type: don’t create a DB column

When we select this element, new fields will be displayed inside the ‘Extra’ tab.

Field

Description

Note

View

what display mode this field will have

categorised into TO DO and DONE or list all elements.

Order By

if we want to order these elements.

 

Order Direction

what direction the order will be

 

Use Form Template

if we want to use the default form or change the form template.

 

 

Allowed Types

what types will be displayed inside this field

 

Default Grid

the default grid that will be displayed

 

Userassociation

View

By selecting the Userassociation type, the element, once added to the form, will allow multiple selection of users.

Field Configuration

Column Type: don’t create a DB column

It is necessary to complete the ‘User Association Type’ field with the value ‘Watch’ (image below).

Custom Event

Deepser allows for the customization of entities, enabling the creation of custom events through dedicated scripting. For instance, certain organizations may require the automatic assignment of priority based on the category selected within a ticket, or may need to modify a ticket upon the insertion of a new comment.

Custom Event Overview

Custom Events can be easily configured through the path: System > Custom Fields.

To view the custom events associated with a specific entity (for example, in the Service module, the “Operations” entity), simply select the corresponding row in the grid.

By accessing the module/entity you wish to modify, you will find the following tabs:

  • Model: Contains the data of the model (or Module/Entity) being modified.
  • Fields: Displays all custom fields created for the model, in addition to system fields.
  • Event: Lists all custom events created for the specific model.
  • Table Management: Allows direct management of the database table.
  • Export/Import: Contains grids of both custom events and fields. Enables efficient import or export of events and fields for effective custom entity management.

Custom Event - Creation

To configure new Custom Events, navigate to the Events tab. Click on the Add Event button in the top-right corner to create a new event.

Once the event is created, the following screen will appear:

The fields we display have the following meaning:

Field

Description

Name

The name of the event being configured.

Type

he type of event (always executed server-side). Possible values:

 

Before Load

Code in the Method field is executed before loading the record.

Before Save

Code is executed before saving the record.

Before Delete

Code is executed before deleting the record.

After Load

Code is executed after the record has been loaded.

After Save

Code is executed after the record has been saved.

After Delete

Code is executed after the record has been deleted.

Position

Execution order of the event.

Status

If enabled, the event will be triggered; otherwise, it will not.

Method

Field containing the PHP code to be executed for the selected event.

Custom Event - Type

Before Save

Before Save events are executed before the model is saved to the database, following an ascending order based on the value of the position field.
A common use case is when, after an entity has been filled in, default values must be assigned before saving. At this stage, the Before Save event can assign default values to empty fields or apply standard values under certain conditions.

Example: Before Save – Assigning Default Values

In the following example, a Before Save event is configured on the DeepService – Operation model. If the priority field of a new ticket is left empty and the selected category is Network, the event automatically sets the priority to High.

The code is inserted in the “Method” scripting area under: System > Custom Fields > Events Tab.

				
					/* It is tested that the current model instance is new */
if($this->isObjectNew()){
    /*  We test that the piority field is not filled in, that the ticket type is Incident, and that the selected category is Network */
    if(!$this->getPriorityId() && $this->getTypeId() == 1 &&  $this->getCategory1() == 5){
        /*  In this case, the Priority field is set to High */
        $this->setPriorityId(2);
    }
}

				
			

After Save

After Save events are executed after the model has been saved in the database, in ascending order based on the position field.

These events are useful when it is necessary to ensure that an object has been saved before performing a configured action. A typical use case involves using the newly generated ID of a record to create a foreign key relationship with another entity.

Example: After Save – Assigning ‘Company Id’ to an Associated User

In this example, an After Save event is configured in the DeepCrm – Contact model. After a contact is saved, the event assigns the related company’s ID to the associated user’s CompanyId field.

Below is the code implemented in the Method scripting area, accessible via the path: System > Custom Fields > Tab Event.

 

				
					// Checks whether there is an Account ID associated with the current object
if($this->getAccountId()){ 
    // Load the Account object using the loadAccount() method.
    $account = $this->loadAccount();
    // From the uploaded Account, retrieve the related Company object
    $company = $account->loadCompany();
    // Load the associated User object using the loadUser() method.
    $linkeUser = $this->loadUser();
    
    // Sets the ID of the Company loaded in the User as CompanyId
    $linkeUser->setCompanyId($company->getId());
    // Save changes to the user object
    $linkeUser->save();
}

				
			

Before Delete

Before Delete type events are executed before a record is deleted from the database and, consequently, from Deepser. These events follow an ascending order determined by the value of the position attribute.

A frequent use case for the use of a Before Delete type Custom Event is the need to delete any references present in other entities related to the record to be deleted, or, record the successful deletion within a dedicated log file.

Example: Before Delete – Logging Record Deletion

In this example, a Before Delete event is configured in the DeepService – Operation model. It logs the deletion of a ticket in a dedicated log file. The code is written in the “Method” scripting area under: System > Custom Fields > Events Tab.

				
					/*  A username of the current user is retrieved */
$currentUsername = Deep::helper('deep_admin')->getCurrentUser()->getUsername();
/*  In Before Delete type events the $this object does not contain the full instance of the
 object but only the 'entity_id' attribute for this reason the instance of the current object is loaded,
 i.e. the one that is about to be deleted via the load method of the deep_service/operation model */
$operation = Deep::getModel('deep_service/operation')->load($this->getId());
/* The string with Title ID and user is formed and will be added to the log */
$logString = 'ID ticket: '. $this->getId() . ' | Titolo: ' . $operation->getTitle(). ' | Utente: '. $currentUsername;
/*  Via the static log method of the Deep class the $logString is added to the file 
 'Ticket_Eliminated.log' if this file does not exist it will be created. */
Deep::log($logString, null, 'Ticket_Eliminati.log');

				
			

After Delete

After Delete events are executed after a record has been removed from the database and from Deepser, following an ascending order based on the position field.

A common use case involves updating or removing references after the deletion of a specific service.

Example: After Delete – Updating the Status of a Device Linked to a Deleted User

In this example, a Delete After event is configured in the DeepAdmin – User model. The event updates the status of a device that was associated with the deleted user.

Below is the code implemented in the Method scripting area, accessible via the path: System > Custom Fields > Tab Event.

				
					
// Create a collection of devices
$deviceCollection = Deep::getResourceModel('deep_cmdb/ci_collection');
// Adds a filter to display only ci = Device
$deviceCollection->addFieldToFilter('class_id', ['eq' => 2]);
// Adds a filter to the collection to select only devices associated with a given username
$deviceCollection->addFieldToFilter('cust_utente_assegnatario', $this->getUsername());
// iterate through each device in the filtered collection
foreach ($deviceCollection as $device) {
    // Sets the status of the device as 0 = inactive
    $device->setData('status', 0);
    // Save changes made to the device
    $device->save();
}

				
			

Best Practices

ID Availability

In Before Save events, the entity_id for new objects will only be available after the record is saved.

Avoid Infinite Loops

Incorrect configuration of Before Save or After Save events can lead to infinite loops, causing memory consumption to grow until it reaches the system limit.

Below is an example of a case where code inserted in an After Save event could generate an infinite loop, resulting in excessive memory consumption until the configured system limit is reached.

				
					/* Incorrect code that would cause a loop */
$linkedId = $this->getCustAssociatedOperation();
if($linkedId){
    $linkedOperation = Deep::getModel('deep_service/operation')->load($linkedId);
    $linkedOperation->setCustAssociatedOperation($this->getId());
    $linkedOperation->save();
}

				
			

Below is the corrected version of the previously shown code, which includes an appropriate check to prevent the generation of unintended loops.

				
					/* orrected version that avoids unintentional loop triggering */
$linkedId = $this->getCustAssociatedOperation();
if($linkedId){
    $linkedOperation = Deep::getModel('deep_service/operation')->load($linkedId);
    /*  Control needed so that the associated ticket instance save event does not 
 trigger an event loop */
    if(!$linkedOperation->getCustAssociatedOperation()) {
        $linkedOperation->setCustAssociatedOperation($this->getId());
        $linkedOperation->save();
    }
}

				
			

Dashboard

Deepser’s dashboard panel is purposefully built to present data in a user-friendly way, employing various forms of data visualization like graphs and charts. This straightforward approach ensures that users can effortlessly interpret and analyze information, enabling them to make informed decisions based on clear insights provided by the visual representations.

Dashboard Overview

The dashboard panel in Deepser is designed to represent sets of data using forms of data visualization such as graphs and charts. In Deepser, the dashboard can be reached clicking on “Dashboard” entry in the main menu:

The dashboard module consists of two main parts: Panel and Chart.

  • Charts are graphic representations for a specific dataset.
  • Panel is a container for charts with similar data analytics.

You can navigate through different panel using the select field on top right corner in the dashboard view:

In the next article we are going to explain the Panel Configuration

Panel Configuration

To configure a new panel you can navigate to System → Dashboard → Panel and click on “Add Panel” button on the top right corner.

Below is the list of available fields and their meaning:

Field:

Description

Code

A unique key for the panel

Title

The name to be displayed for the panel.

Position

The position where the panel will be displayed in the panel list.

Enable Groups

It’s a multiselect field where different user groups can be included to have visibility on the panel.

Status

It’s a select field that sets the panel to enabled or disabled.

In the next article we are going to explain Chart Configuration

Chart Configuration

To configure a new chart you go to System → Dashboard → Chart and click on “Add Chart” button on the top right corner.

Below is the list of available fields and their meaning:

Field:

Description

Panel

A select field to choose on which panel you want this chart to show.

Type

If selected you can create a chart of custom type.

Chart Type

It’s only visible if a custom type is selected on the above field. It contains different chart types such as pie, bar, horizontal, line etc.

Code

It’s a unique key to identify the chart.

Title

It’s the name to be displayed of the chart.

Columns

It represents the width of a chart square on the panel.

Position

The position where the chart will be displayed on the panel.

Cache Time

The duration in which the chart queries will be saved in the cache.

Expression

Here it’s written all the needed custom code and database queries to style the chart and fill it with data.

NOTE: Chart configuration requires a deep understanding of utilizing advanced coding within the scripting area. Specifically, chart datasets can only be manipulated through the “expression” field.

Project

A Project Module for Deepser focuses on streamlining project management processes by providing a comprehensive suite of tools to plan, execute, and monitor projects effectively. This module enables users to create and manage project timelines, assign tasks, track progress, and collaborate with team members seamlessly. One of its key features is the Gantt chart, which visually represents project schedules, making it easy to track dependencies and milestones.
 

Project Module ensures that resources are optimally allocated, deadlines are met, and project objectives are achieved efficiently. By leveraging advanced analytics and reporting features, the module also offers valuable insights into project performance, helping teams to identify areas for improvement and ensure the successful completion of their projects.

Project Module

The project module in Deepser is a tool used for Project Management and scheduling. This module is integrated with Gantt which makes it possible to manage tasks and their dependencies, track their progress etc. Like every other module in Deepser, this module has a main Entity which is Project, and this entity can have it’s own types.

When you click on “All” from the menu the Grid with all the projects will show. To create a new Project just click on right side corner button.

This page will be opened. From now, you’re free to fill the FormTemplate values:

Below, you will find a list of all the fields and their purposes:

Field

Description

Name

Project Name.

Duration Unit

Select field which indicates the duration of tasks inside this project: Days or Hours.

Type

Project defined Type.

Description

Project Description.

Start Date

This contains the date from which the project will start.

Default Time Scaling

Select field where you can choose the time scaling for Gantt which can be: 4 months, 1 week etc.

Default Auto Scheduling

When switched to “ON”, tasks will be automatically scheduled once they are created.

Use Project

When switched to “ON” allows this project to be used in other modules in Deepser like: Operation, CMDB etc.

View Groups

Multiselect Field with all the groups that can only view this project.

View Usernames

Multiselect Field with all the user that will be able to view this project.

Edit Groups

The groups selected on this field will be able to view and edit this project.

Edit Usernames

The users selected on this field will be able to view and edit this project.

To view this project on Gantt chart, you can click on the button at top right corner, that appears after the project is saved.

Gantt

To view any project on Gantt chart, you can click on the button at top right corner, that appears after the project is saved.

Gantt chart in Deepser is divided into two main parts. On the first one there is a table with all the Tasks for this project. The header columns of it represent fields of Task model.

There are unlimited levels of tasks. As you can see from the screenshot below, you can create:

  • “First level” tasks by clicking the main + button highlighted.
  • Subtasks by clicking the small + button on the right side. Additionally, you can copy and delete subtasks from the yellow and red icon on the right side.

Gantt Chart

Gantt Chart in Deepser visualises all the tasks for a project, based on their start date and duration.

Time Scale -> It scales the Gantt calendar based on its options. The default time scale for it will be the project “Default Time scale” value. For E.g. if the option selected is 2 weeks, the chart will be divided into every two weeks duration columns.

Expand -> It is used to define the level of tasks that will be shown on the chart. Level 1 option is for all the main tasks and level max shows all the tasks and subtasks. If there is a level of subtasks of more than 1, a new option level will be shown on the list.
For E.g. If a subtask has its own subtask, Level 2 option will be added on the list.

Hide Task List -> By clicking this button you can hide the tasks table.

Legend

  • Task Bars: Represents individual tasks or activities within the project. The length of a bar indicates its duration. Bars with a blue colour, are main tasks that have their own subtasks, while bars with the green colour do not have subtasks.
  • Dependencies:  Orange arrows indicate relationships between tasks. Arrow starts source Task to the Dependent Task.
  • The yellow arrow on the chart is visible when a task has a Deadline Date.
  • The red arrow on a task means that there is a constraint for that task. When you hover on the arrow it shows the constraint type.
  •  This symbol represents a task that is a Milestone. Is Milestone toggle is set to “Yes”.

Project Task

This is the Formtemplate showed when a task is opened:

Field

Description

Title

Title for this task.

Is Milestone

When switched to “ON” it marks this task as a main phase for this project.

Deadline

It sets a constrain for this task to finish at a particular date.

Started At

It is automatically populated with the start date of the project, but it can be changed based on the needs for this task.

Duration

It sets a duration for the task which can be measured in days or hours, based on the “Duration Unit” field on the project. It is automatically calculated if the “Ended At” field is set.

Ended At

It sets the date when the task is planned to end. It is automatically calculated if the “Duration” field is set.

Assigned User

Select field where you can assign this task to a user.

Status

Status field that represents the task’s progress, with values: ‘’To do’’, ‘’in progress’’, “Done’’,” Deleted”.

Completion Percentage

Progress bar field measured in percentage, where you can set percentage of completion of this task.

Description

Field to add a description for this task.

  • Link and Constraint:

Constraint Type -> This field restricts on when the task should finish. When set to values “as soon as possible” or “as late as possible” you can not set a constraint Date for this task. For every other value a constraint date should be set.

Constraint Date -> Based on the constraint type you can set a constraint date for this task.

Link -> This is a grid with all the dependency tasks that are linked to this task. You can directly add a dependency to this task by using the buttons “Add Dest” or “Add Src”.

Add Dest Button -> By clicking “Add Dest” button you can add a task that is dependent on this current task. Src Id field is autocompleted with the current task and on the Dest Id field, you can select the dependent task.

Type:

  • Finish to Start: The dependent task cannot start until the preceding task finishes.
  • Start to Start: The dependent task cannot start until the preceding task starts.
  • Finish to Finish: The dependent task cannot finish until the preceding task finishes.
  • Start to Finish: The dependent task cannot finish until the preceding task starts.

Add Src Button -> Creates a dependency for this task based on another task. The dest Id field is autocompleted with the current task and on the “Src Id field” you can select the main task linked to this task.

  • Configuration:
    • Model Alias -> Field to choose a Deepser model that is connected to this task. This field is autocompleted with the project model, but you can also choose for E.g. operation.
    • Model Id -> You can choose the model to connect this task to. This field is auto-completed with the current project.

Subtask

For every task on the table, there is an option to add a subtask by clicking on the “+” button.

The fields for a subtask are the same as for a main task, the difference is that this subtask is directly dependent on the main task.

Resource Grid

To have a better and detailed look of how tasks are allocated across days on the project, you can refer to the resource grid.

On the left side you see the Assigned Users, their respective tasks and the working hours allocated to each task. On the right side, a calendar displays the hours worked each day by the assigned user on the tasks. The standard working hours, such as 8 hours per day, are based on the Project Calendar. Any hours worked beyond these standard hours are labelled red on the calendar.

The calendar displayed in the Resource Grid is configured through the Project’s Calendar Model. To set up a new project calendar, you can follow the same procedures as used for the default calendar module.

Calendar

In Deepser, the Calendar module allows users to configure and then view work calendars based on internal or external sources.

One of the default calendars natively configured in Deepser is the Tasks calendar.

Through this calendar, it is possible to view all the tasks present in the system and apply filters on the status, the assigned user, and the type of Task.

In any case, it is possible to intervene to configure and view personalized calendars.

Calendar Configurations

As an administrator user, by accessing “System > Calendars” you can proceed to configure new calendars.

From this section it is possible to configure two different types of calendars:

Internal Calendar Configuration

If the source of the data is internal to Deepser. So in this case it will be necessary to define the starting collection by reading the information directly from one or more areas of Deepser.

Specifically, if you create a new internal calendar, you will be asked for the following information:

Field

Definition

name

It’s the name of the calendar. This name will be displayed on the Deepser menu on the right.

position

Using this field you can decide the calendar position in the right menu.

description

Descriptive field

icon

Icon related to the type of calendar you configure

Enabled Groups

With this field you can add the visibility to a specific group.

status

Using this field, you can enable or disable the calendar. If the calendar is disabled, cannot be displayed in the menu.

Sources

With this particular field you can configure the data source for your calendar and set filters too.

Source Configuration

The configuration of the source of an internal calendar is divided into 2 sections.

A section for configuring the data collection and how to display data on the calendar and a section for configuring filters to be applied to the main collection.

Below is an example:

Using the “1” button it is possible to proceed with the addition of a new data source, which once configured will be displayed as the main element of the source field (In this the element called “Worklog” identified by the number 2).

Using the “3” button it is possible to proceed to add a new filter on the previously configured collection (“2”). Once the filter is configured, it will appear as a sub-item of the main collection “4”.

There will also be edit and delete buttons for both the data collection “2” and the related filters “4”.

The data source addition screen, which can be viewed following the addition click on the “1” button, will consist of the following fields:

Field

Definition

name

With this field, you can give a name to the data collection used.

code

Through this field, it is possible to give a code to the data collection used. The code can then be used on the scripting area side.

start_date_field

This field indicates the field name used to identify the start date of a calendar event according to the collection used.

end_date_field

This field indicates the field name used to identify the end date of a calendar event according to the collection used.

status

Field to enable or disable the data source used.

collection_code

Through this scripting area, it will be possible to define the collection you intend to use and how to manage it.

drop_code

Through this scripting area, it is defined what will happen to the event when it is dragged and dropped on the calendar. You can set the fields that represent start and end date on the collection, with the new start or end date of the calendar, where the event was dropped.

event_name

Through this scripting area, it will be possible to define through JavaScript code, the way an event is displayed within the calendar.

tooltip_code

Through this scripting area, it will be possible to define via JavaScript code, the tooltip that can be displayed on calendar events, and possibly configure predefined actions.

color_code

Through this scripting area, it will be possible to define through JavaScript code, a different coloring of the events based on conditions (e.g. Based on event status).

drop_js_code

Through this scripting area, using JavaScript code,  you can define what will happen after the event is dropped.  On this area for example, you can set a modal or an alert interaction to warn the user that the date will change based on where the event was dropped, or as well you can set a page reload after the event is dropped.

The screen for adding a filter to a collection, which can be viewed following the click to add the “3” button, will consist of the following fields:

Field

Definition

name

With this field, you can give a name to the filter used.

code

Through this field, it is possible to give a code to the filter used. The code can then be used on the scripting area side.

status

Field to enable or disable the configured filter.

html_element

Through this scripting area, it will be possible to define through PHP code, the mode of display and management of the filters applicable to the calendar.

collection_code

Through this scripting area, it will be possible to define through PHP code how to apply filters to the reference collection.

Calendar Configuration Example

Calendar Module can be helpful to track all the worklogs and also be able to directly modify their duration or start date. First of all, create a calendar entity called “Worklog Calendar” and then configure the main part, which is the source.

This calendar will be based on the ‘started_at’ field of the activity model.

  • collection_code
				
					// Retrieve the activity collection and filter it by type of worklog.
$collection = Deep::getResourceModel('deep_activity/activity_collection') ->addFieldToFilter('model_alias','deep_service/operation')->addFieldToFilter('type',2);
// A time range is set on the started_at field, by using $start and $end variables , which correspond to ‘start_date_field’ and ‘end_date_field’.

$collection->addFieldToFilter('started_at', ['gteq'  => $start]);
$collection->addFieldToFilter('started_at', ['lteq'  => $end]);

				
			
				
					// A join operation is performed on the activity collection, in order to access service operation fields and display them on the calendar
$collection->getSelect()->join(
    array('operation_table'=>'deep_service_operation'),
    'main_table.model_id = operation_table.entity_id',
    ['assigned_username'=>'operation_table.assigned_username','ticket_title'=>'operation_table.title'  ,'assigned_group_id'=>'operation_table.assigned_group_id',
'ticket_status'=>'operation_table.status','operation_type'=>'operation_table.type_id']);
// it applies the filters selected on the calendar
 $this->applyFilters($collection);

				
			
				
					//Loop through each worklog
foreach ($collection as $worklog)
{
// set the accurate timezone for the start date that comes from database
    $startEvent = $this->convertToTimezone($worklog->getStartedAt());
// calculate the end of the worklog by  using duration field
    $endDate = date_create_from_format('Y-m-d H:i:s',$startEvent);
    $duration = $worklog->getDuration();
    $endDate->modify("+ $duration second");
    $endDate = $endDate->format('Y-m-d H:i:s');
// convert end date to an accurate timezone
    $endEvent = $this->convertToTimezone($endDate);
// Retrieve the url of the ticket
    $modelUrl = Deep::getUrl('*/service_operation/edit',['id'=>$worklog->getModelId()]);
// Retrieve the User who create the worklog
    $createdByUser = Deep::getModel('deep_admin/user')->loadByUsername($worklog->getCreatedBy())->getDisplayUsername();
// worklog data is loaded and then converted to an array
    $worklog->loadTypeData();
    $worklog->toArray();
// set the ticket Url  as an array element
    $worklog['model_url'] = $modelUrl;
// check if start date  and end date are populated  correctly, then add the current worklog as an event in the calendar.
    if($worklog->getStartedAt() !='' && $start !='' && $end !='')
    {
        $this->addEvent($startEvent,$endEvent,$worklog);
    }
}

				
			
  • Event_name
				
					/* event variable is a javascript object that is populated with all worklog’s fields. The syntax to access a field is event.” Field name”, in this case ticket_title field is used.
On this section an html text element should be returned, such as <p>, <span> <h1> etc.
*/
const eventTitle = "<span style='color:black'>"+event.item.ticket_title+"</span>";
    return eventTitle;

				
			
  • drop_code
				
					// load worklog by using the $item variable, which is an array with all worklog’s fields.
$worklog = Deep::getModel('deep_activity/activity')->load($item['entity_id']);
// check if $start is set after the event is dropped
 if ($start)
 {
  // Set started_at field to the new start date and save the model
     $worklog->setData('started_at',$this->convertToSystemTimezone($start));
     $worklog->save();
 }

				
			
  • Tooltip_code
				
					// create a main div element to wrap the tooltip
var html = jQuery('<div>');
   // create an element to contain the start_date field
   var startDateContainer = jQuery('<div>');
   var startedAt = new Date(event.item.started_at+'+00:00');
// Set  start date to the right timezone and date format
    startedAt = startedAt.toLocaleString('it-IT',{timeZone:'Europe/Rome', day:"2-digit",month:"2-digit",year:"numeric",hour: '2-digit', minute:'2-digit'});
// modify the text of the start_at element by adding its value
    startDateContainer.text("Started At: "+startedAt);
// add styles to its text
    startDateContainer.css('padding', '5px 0');
    startDateContainer.css('font-weight', 'bold');
// append the started_at element to the main div 
    html.append(startDateContainer);

// create a paragraph element that will contain the ‘created by user 
    var createdByContainer = jQuery('<p>');
    createdByContainer.text('Technician: ' + event.item.technician);
    createdByContainer.css('padding', '5px 0');
    createdByContainer.css('font-weight', 'bold');
    html.append(createdByContainer);
 // select the element which is an event on the calendar, and initialize tooltip with specific configurations.
    jQuery(element).tooltipster({
        theme: "tooltipster-shadow", // specify the tooltip theme
        interactive: true, // Makes the tooltip content interactive
        side: "right", // positions the tooltip on the right side of the target element
        content: html  // append the above created tooltip to the  content
    });
// adds an onclick event listener the element, which opens the ticket where the worklog is added
    jQuery(element).on('click', function(){
        window.open(event.item.model_url, '_blank');
    });

				
			
  • drop_js_code
				
					//    create a confirm box to warn the user about dropping the event
 if (confirm('Are you sure?'))
        return true; // if confirmed event is dropped
    else
        return false;

				
			

Filters

Worklogs will be filtered by : Ticket Status, Ticket Type, Assigned Group and Assigned user.

  • html_element
				
					$statusList = Deep::helper('deep_list')->loadListValues('service_operation_status')->toOptionHash(); // Retrieve operation status values
// retrieve operation types
$operationTypes = Deep::getResourceModel('deep_service/type_collection')->toOptionHash();
// retrieve groups values
$groups = Deep::getResourceModel('deep_group/group_collection')->toOptionHash();
$users =[];
// Every filter is added by using $this->addField()
$this->addField(
    'operation_table.status', // filter name which should be unique
    'select', // filter field type
    array(
        'label' => ' Ticket Status', // filter label 
        'name'  => ''operation_table.status', // filter name
        'multiple' => 'multiple', // sets this filter as multiselect
        'values' => $statusList // set the values from which the select will filter
    )
);
$this->addField(
    'operation_table.type_id',
    'select',
    array(
        'label' => 'Service Type',
        'name'  => 'type_id',
        'multiple' => 'multiple',
        'values' => $operationTypes
    ));
' Assigned Group',
        'name'  => 'operation_table.assigned_group_id',
        'multiple' => 'multiple',
       'values' => $groups
    ));

				
			
  • collection_code
				
					// loop through all the filters and filter the collection based the column name. 
// In this case it is required that filter and collection field have the same name
foreach (  $this->getRequestFilter() as $k => $v){
    if ($v)
    {
        $collection->addFieldToFilter($k, ['in' => $v]);
    }
}

				
			

External Calendar Configuration

If the source of the data is external to Deepser. Through this section, for example, you can intervene to configure a calendar whose data source is an external calendar (for example your Google calendar).

For External calendar the following section should be configured:

Calendar

In the calendar module, you can name the calenda, define the “Type” as Google Calendar or Outlook Calendar, in “OAuth Client” you can select the Client you previously created, and choose the desired calendar in “Unique Id”.

(To view a complete example, you can check the google calendar configuration example accessible here)

Source

External source is used to link deepser models like operation, activity or task with external calendars. On the external source multiselect field, you can choose an existing source, or create a new one.

Field

Description

Name

On this field, you can set a name for the source.

Model

Select field where you can choose the model you want to use on the calendar.

Status

Select field where you can choose to enable or disable the source.

Prepare Collection

With this query builder you can filter the collection chosen based on their fields.

Upload Field Config

With this scripting area, you assign values from the model as calendar events.

Download Field Config

With this scripting area, you can create models with values from the calendar events.

Upload Field Config

				
					/*event variable is an array with keys of name, description, start and end
This keys will be mapped to the model values.
*/
$event['name'] = $model->getTitle();
$event['description'] = $model->getDescription();
$event['start'] = $model->getCreatedAt();
$event['end'] = $model->getDueDate();

				
			

Download Field Config

				
					/* model variable corresponds to the chosen model and its data is set by the calendar event */
$model->setTitle($event['name']);
$model->setDescription($event['description']);
$model->setCreatedAt($event['start']);
$model->setDueDate($event['end']);

				
			

External Calendar - Google Calendar Configuration Example

Create an OAuth Client in Deepser

In the Deepser Configuration in System > Tools  > OAuth  > Client > Add Client: enter a name, define  the type  as  Calendar, set the provider as Google and save.

Once saved, copy the generated Redirect URI.

Go to the Google Cloud Platform, and log in. Once this is done, click on  the  menu at the top where all the projects are listed.

A window will open where you can create a new project using the New Project button. All you have to do is give your new project a name and click on the Create button.

To enter the newly created project  , repeat the process above:  click on the menu that groups all the projects and click on the name of the newly created project to start the configuration.

Once you have entered the project, click  on the OAuth Consent Screen  section in the menu on the left: in User Type select External and proceed by clicking Create.

Give the application a name, enter the email used for access  in User Support Email and in Developer Contact Information. Proceed to Save & Continue.

Under Scopes, press the Add or Remove Scopes button.

In the form below the paragraph Add Manually, copy and paste the following address https://www.googleapis.com/auth/calendar. Then  click Add to Table, and then  click Update. Then click save and  continue to continue.

In  the Trial Users section, click on Add User and enter the email address with which you logged in to the platform.

Under Summary , click Save & Continue.

Now go to  the Credentials  section of the menu on the left and create a new Oauth Client ID through the Create Credentials button.

In the drop-down menu, select OAuth Client ID.

Select in  the application type Web Application, give it a name, and under Authorized Redirect URIs,  paste the URI that you previously generated and copied. Finally, click Create.

The Client  ID  and Client Secret will be generated and copied and entered into the respective fields of the OAuth Client previously started to configure in Deepser.

Once saved, proceed with the Client Validation by clicking on the Validate button.

Then log in and click Continue.

Tick the boxes regarding the read/write permission of Google calendars and click Continue.

If all the steps have been carried out correctly, the Client will be validated and active.

On the Google platform, go to Library. Then search for Calendar.

Enable Google Calendar.

Go  to Google Calendar(https://calendar.google.com/)  and  create a new calendar to be shared with Deepser, otherwise you can use the calendars already present and prepared by default.

To create a new calendar,  click on  the + button  next to the  Other calendars label.

Give the calendar a name, a description (if any), and the desired time zone. Save with Create Calendar.

In Deepser, go to System > Calendars  > External > Calendar and add a new calendar.

Give the calendar a name, define  the Type as Google Calendar, in OAuth Client select the Client you previously created, and in Unique Id select the desired calendar.

External Calendar – Outlook Calendar Configuration Example

Creating OAuth Client on Deepser

In the Deepser Configuration in System > Tools  > OAuth  > Client > Add a new Client with the following values:


Name: You can choose your custom name

Provider: Azure

Type: Azure App Permission

Then you can proceed with saving.

After saving, Deepser will provide to you the “Redirect URI” that you need to copy and use for configuration on Azure Admin Portal.

Creating your APP on Azure

After complete the first step of configuration on Deepser go to the Azure portal and sign in with your Office 365 account.

Once logged in, click on App Registrations

Then click New Registration.

On App Registration we can proceed entering the following information:

  • Name for the new App,
  • Supported Account as “Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)”

In conclusion you can click on “Register” button.

App Certificate & Secret

Under “Manage > Certificates & secrets” in the menu, you can create a secret. During the configuration process, you’ll need to set its expiration time and copy its value, which will be used later to complete the configuration in Deepser.

The copied secret value will need to be entered into the field “Client Secret” on the oauth client record in Deepser:

Notes:

  • Be sure to copy the value of the secret, not the Secret ID.
  • You must copy the secret value during the creation phase, as you won’t be able to access it later (in that case, you would need to recreate it).
  • If you set an expiration for the secret, remember to renew it before the expiration date

App API permissions

Under “Manage > API permissions” in the menu, you can add the following permissions for Microsoft Graph and then run the “Grant admin consent” action:

  • Calendars.Read as Application Permission
  • Calendars.ReadWrite as Application Permission

Click on “Add a permission” to open the permission selection prompt:

Then select “Microsoft Graph” as API permission to use:

From this screen you can choose Application permissions and use the search field for research the desired permission to add:

After adding all desired permissions, you can run Grant admin consent command:

Before going back to the Oauth Client in Deepser and complete the configuration, we can note down all the Azure information to be used in Deepser Oauth client configuration. Below is a summary of the Azure information to be reported in Deepser:

  • Secret Value

NOTES: Be sure to copy the value of the secret, not the Secret ID.

You must copy the secret value during its creation phase, as you won’t be able to access it later (in that case, you would need to recreate it).

 

  • Application (client) ID
  • Directory (tenant) ID

Complete OAuth Client Configuration on Deepser

You can now return to the Deepser Oauth Client record to proceed with the completion of configuration.

Deepser – General Tab

If not already done, please configure “Provider” and “Type” field respectively as “Azure” and “Azure App Permission”.

Then we can proceed to set Tenant ID, Client ID and Client Secret:

In the “Client ID” field, enter your “Application (client) ID” from Azure.

In the “Client Secret” field, enter your “Secret Value” from Azure.

In the “Tenant ID” field, enter your “Directory (tenant) ID” from Azure.

In the “Tenant ID” field, enter your “Directory (tenant) ID” from Azure.

Calendar Configuration

By configuring an External Calendar, you are able to sync all desired entities from Deepser to Outlook Calendar. The synchronization works in the following ways:

  • Deepser can create events on the Outlook calendar
  • Deepser can delete events (only previously synchronized) on the Outlook calendar
  • Outlook Calendar can update previously synchronized events on Deepser

In the example below we configure a sync between tasks of a specified user in Deepser with his calendar on Outolook.

External Source Configuration

An external source is used to link Deepser models, such as operation, activity, or task, with external calendars. An admin user can add an external source by navigating to SYSTEM > CALENDARS > EXTERNAL > SOURCE.

Below an example for an “External Source” based on Task syncronization between Deepser and Outlook Calendar:

  • Name: You can choose your custom name
  • Model: You need to select “DeepTask – Task” as model.
  • Prepared Collection: You need to filter tasks you want to sync. In this example we are configuring an external source for sync all tasks assigned to user “oauth1/example@ex.com”.
  • Upload Field Config:
				
					$event['name'] = $model->getTitle();
$event['description'] = $model->getDescription();
$event['start'] = $model->getStartedAt();
$event['end'] = $model->getEndedAt();
				
			
NOTE: with this field, you can map fields to create events on external calendar.
 
  • Download Field Config:
				
					$model->setTitle($event[‘name’]);
$model->setDescription($event[‘description’]);
$model->setStartedAt($event[‘start’]);
$model->setEndedAt($event[‘end’]);
				
			

NOTE: with this field, you can map fields to update tasks on Deepser.

External Calendar Configuration

After External Source configurations, you can proceed with the external calendar configuration for each User you want to configure.

An Admin user can add an External Calendar from SYSTEM > CALENDARS > EXTERNAL > CALENDAR.

Below an example for an “External Source” based on Task syncronization between Deepser and Outlook Calendar for the user “oauth1/example@ex.com”:

Below are the details of the fields to be configured:

  • Name: Set your own custom name

  • Cron Expression: Set how frequently the synchronization will be executed (every minute in the example).

  • Type: Select “Outlook Calendar (Graph v1.0)” for Outlook calendar sync.

  • OAuth Client: Select the previously created OAuth client.

  • User: Choose the Outlook user you want to sync.

  • External Source: Select the previously created source (tasks filtered by the assigned user).

  • Unique Id: Specify the calendar on which you want to sync the tasks.

  • Start Date: Only events (and changes to events) with a start date and time equal to or later than this will be retrieved from the server.

  • Timezone: Select your current timezone to handle dates consistently between Outlook and Deepser.

 

NOTE: The operations indicated in the “External Source Configuration” and “External Calendar Configuration” sections must be repeated for each user for whom synchronization with the Outlook calendar is to be enabled.

Calendar Usage

Once the calendars have been configured, backend users will be able to access the Calendar item on Deepser from the main menu and view the calendars according to the visibility set in the configuration.

Each configured Calendar can have its peculiarities as the degree of customization is very high. In any case, normally there will be an area dedicated to the applicable filters and the actual calendar with the activities displayed inside.

The tasks displayed in the calendar, if configured correctly, can also have predefined actions that can be performed via popup tooltips.

Below is an example of the default Deepser Task calendar:

Survey

The Survey Module in Deepser allows you to easily create, distribute, and analyze customer needs. It integrates with support tickets to gather feedback, helping improve service quality and customer experience.

Survey Overview

The survey module is used to collect feedback from users (clients) by generating questionnaires. This module includes the following entities: Designer, Survey, and Dashboard.

Designer: Allows you to create a template for a survey that you can use as the basis for multiple surveys.

Survey: Contains all the logic for visibility, questions, and answers.

Dashboard: Provides a clear and concise visualization of key data and real-time information regarding created surveys.

Designer

The ‘Designer’ module is designed to organize, manage, and create surveys using predefined templates configured beforehand.

Consequently, within a ‘Designer’ type, we find the same structure as a ‘Survey’ type record, with the difference that the fields are used to preconfigure the surveys created from it.

To create a survey, you first need to generate a template for it. You can accomplish this by navigating to Survey à Designer and then clicking on “+Add Survey Template”:

The following screen will appear:

All the fields available in the Survey Template (Designer) will be available in the Survey record after its creation.

So, in the survey template, the fields have no functionality other than being inherited by the surveys created from it.

Below is the list of available fields and their meaning for the Designer module:

Field

Description

Name

The text field that is used to name the surveys on the creation.

In a survey template, multiple survey records can be created. When you click the “Create Survey” button, the system prompts you to enter a name for the new survey, suggesting the template name as a default.

 

 

Intro Notes

Editor fields where you can insert a short introduction for the surveys.

Final Notes

Editor fields where you can insert a short final note for the surveys.

Description

Internal Description field for the surveys

Is Anonymous

If set to Yes, it allows recipients to submit anonymous answers.

Show Submit in All Pages

If set to Yes, it allows to show the “Submit” button on all survey pages (if there is more than 1).

Expires in Days

Numerical field which sets a time of expiration for the survey in days.

Expires in Hours

The numerical field sets the time of expiration for the survey in hours.

Expires in Minutes

Numerical field which sets a time of expiration for the survey in minutes.

Fronted Visibility

It allows us to enable the surveys for the frontend portal (portal for unregistered users).

Send Email

If set to Yes, it allows to send a mail on survey creation.

Groups

Multiselect fields where you can choose the groups who should have visibility on the created survey.

Users

Multiselect fields where you can choose the users who should have visibility on the created survey.

Send Emails

If set to yes, can permit email sending on survey creation.

Mailbox

By this field, you can choose a specific mailbox to use for sending emails.

Use Template

If set to “ON”, it enables “Email Template ID” to be used for email sending on survey creation.

Email Template Id

With this field, you can select a preconfigured email template to be used for the email sent on survey creation.

Subject

This field will be displayed only if the “Use Template” field is set to “OFF”, and it is used to set a subject for the email sent on survey creation.

In this field, you can use the variables “users” and “survey” to create a dynamic template.

Example:
to get the survey id you can use: {{var survey.getId()}}

Email HTML Body

This field will be displayed only if the “Use Template” field is set to “OFF”, and it is used to set a mail body for the email sent on survey creation.

In this field, you can use the variables “users” and “survey” to create a dynamic template.

Example:
to get the survey id you can use: {{var survey.getId()}}

Status

With this field, you can enable or disable a survey.

Surveys

Is a relation grid that shows all the surveys generated from this survey template.

Questions creation

After creating the base for the survey, you can proceed to the question creation. You can do it by clicking the “Open Designer” button in the top right corner:

To add a new question to the survey, click the “+” button and select the question type.

Once the question row is created you can edit it by selecting the edit icon to access further options:

The following screen will appear:

Below is the list of available fields and their meaning:

Field

Description

Question

The text field that adds the question text.

Description

Editor field to add a description for the question.

Required

Toggle button that can make a question mandatory on the survey.

Dependency Expression

It is used to add rules and make this question dependent on another question.


Based on the previously selected question type, on the configuration Fieldset, you can handle the following configurations:

Text Type

  1. For the Boolean question type you can configure how you want to render the question, which can be: Textbox, Textarea, or Advance Editor.
  2. You can also apply a pre-defined type of data validation like Email, URL, Telephone, Numeric, or Alphanumeric.
  3. And then you can set a placeholder.

Boolean Type

For the Boolean question type, you can configure how you want to render the question, which can be: a toggle button, select (with Yes/No values), or a checkbox.

Attachments Type

With this type, you can choose the min and the max file number to upload by the field.

Generic Choices, Multiple and Select Types, Radio, Checkboxes

These types of questions are represented in the form of select fields.

Choices: this is a select field where you can choose pre-created lists and click on “Load Choices”.

To create a new list of choices you can click on the “+” sign and add key(value)-> label pair list values and then click on save choices.

Key Type: select the field to choose the type of key for the list which can be numeric or alphanumeric.

Is Multiple: When toggled to ON the user can choose multiple values on the question.

Rating Type

The rating question is a form of evaluation that is visualized in stars. For this question type on the configuration fieldset, you can set a Max Value that represents the maximum number of stars in the rating question.

Ranking Type

With this type, you can allow respondents to rank a list of predefined choices. You can add choices in the same way as other select types, and you can also randomize the list of defined choices by clicking on the “Randomize Answers” toggle box:

Number or Percentage Type

With a numeric type, you can specify the minimum and maximum values in the configuration fieldset:

Page

The page type doesn’t require any specific configuration. It should simply be inserted between two questions.

Questions preview

On the main page containing the questions, you can find the question preview frame:

After changing your questions, you can always update the survey preview by clicking the “Update Preview” button.

Survey Creation

After the saving of the template and the creation of the related questions, you will be able to create a Survey record by clicking the “Create Survey” button in the top right corner in the screen:

Clicking on it will bring up a popup that informs you about the number of emails that will be sent (based on Groups and Users fields). In this popup, you can also choose a name for the survey you create by entering it in a text field.

After the creation, on the designer module, you can view the newly created survey under the relation grid field “Surveys”:

On this grid, you can also use the “Update Surveys” button after selecting one or more survey records from the grid to update all their related data.
With the “Update Surveys” button, the main data and related questions will be updated based on the associated survey template.

Survey

Survey is the main module of the three mentioned and it contains all the information that can be useful for decision-making purposes.

In the survey module, all fields related to email sending cannot be changed because the notification email can only be sent upon survey creation.

 

Below is the list of available fields and their meaning for the Survey module:

Field

Description

Template

Text field auto-populated with the survey template related to this survey.

Name

The text field that is used to name the survey.

 

This field can be selected in the dashboard model to verify the survey results.

 

It will be inherited from the survey template and can be changed.

Model Alias

A survey can be related to another model which can trigger the survey creation.

 

It can be changed.

Model Id

The ID of the model related to the survey.

 

It can be changed.

Intro Notes

This field will be displayed at the beginning of the survey before all the questions.

It will be inherited from the survey template and can be changed.

Final Notes

This field will be displayed at the end of the survey after all the questions.

 

It will be inherited from the template and can be changed.

Description

Internal Description field for the surveys.

It will be inherited from the template and can be changed.

Is Anonymous

If set to Yes, can permit anonymous answers by recipients.

It will be inherited from the template and cannot be changed.

Show Submit in All Pages

If set to Yes, it allows to show the “Submit” button on all survey pages if provided.

 

It will be inherited from the template and cannot be changed.

Expires in Days

Numerical field which sets a time of expiration for the survey.

The count starts from the moment the survey is created. Once the survey expires, the main status will be changed automatically to “Expired” and the flag “Is Expired” will be set to Yes.

 

It will be inherited from the template and can be changed.

Expires in Hours

Numerical field which sets a time of expiration for the survey.

The count starts from the moment the survey is created. Once the survey expires, the main status will be changed automatically to “Expired” and the flag “Is Expired” will be set to Yes.

 

It will be inherited from the template and can be changed.

Expires in Minutes

Numerical field which sets a time of expiration for the survey.

The count starts from the moment the survey is created. Once the survey expires, the main status will be changed automatically to “Expired” and the flag “Is Expired” will be set to Yes.

 

It will be inherited from the template and can be changed.

Is Expired

If set to Yes, it indicates that the survey has expired.

Fronted Visibility

It allows us to enable the surveys for the frontend portal (portal for unregistered users).

 

It will be inherited from the template and cannot be changed.

Send Email

If set to Yes, it allows to send a mail on survey creation.

 

It will be inherited from the template and cannot be changed.

Groups

Multiselect fields where you can choose the groups who should have visibility on this survey.

 

CREATION: Upon survey creation, it will be used to send an email to all users in the specified group (assuming all other email fields are correctly configured).

 

CREATION/EDIT: You can modify this field to enable or disable the visibility of the survey for a specific group. It is also used to allow using the survey as a filter in the “Charts” tab within the dashboard module.

 

It will be inherited from the template and can be changed.

Users

Multiselect fields where you can choose the users who should have visibility on the created survey.

 

CREATION: Upon survey creation, it will be used to send an email to all users selected (assuming all other email fields are correctly configured).

 

CREATION/EDIT: You can modify this field to enable or disable the visibility of the survey for a specific user. It is also used to allow using the survey as a filter in the “Charts” tab within the dashboard module.

 

It will be inherited from the template and can be changed.

Send Emails

If set to yes, can permit email sending on survey creation.

 

NOTE: All other email fields should be configured to allow sending mail.

Mailbox

By this field, you can choose a specific mailbox to use for sending emails.

 

It will be inherited from the template and cannot be changed.

Use Template

If set to “ON”, it enables “Email Template ID” to be used for email sending on survey creation.

 

It will be inherited from the template and cannot be changed.

Email Template Id

With this field, you can select a preconfigured email template to be used in emails sent on survey creation.

 

It will be inherited from the template and cannot be changed.

Subject

This field will be displayed only if the “Use Template” field is set to “OFF”, and it is used to set a subject for the email sent on survey creation.

 

In this field, you can use the variables “users” and “survey” to create a dynamic template.

 

Example:
to get the survey id you can use: {{var survey.getId()}}

 

It will be inherited from the template and cannot be changed.

Email HTML Body

This field will be displayed only if the “Use Template” field is set to “OFF”, and it is used to set a mail body for the email sent on survey creation.

 

In this field, you can use the variables “users” and “survey” to create a dynamic template.

 

Example:
to get the survey id you can use: {{var survey.getId()}}

 

It will be inherited from the template and cannot be changed.

Status

With this field, you can enable or disable a survey.

 

It will be inherited from the template and can be changed.

Results

Is a relation grid that shows all the survey results in progress or completed ones. You can also directly add a Result by clicking on the “Add Result” button.

Emails

Is a relation grid for all the emails that has been sent for this survey to users and groups on survey creation.


Here Results and Email grid related to the survey:

Manual Using

By clicking on the “Add Result” button on the “Results” relation grid, you can add a new result for a survey, and you can also relate it to a specific user.

Anyway, no email will be sent to recipients. The email for the survey is only sent upon survey creation.

The available fields are the following:

Field

Description

Template Id

Auto-populated field with the ID of the survey template related to this survey.

Survey

Auto-populated field with the related survey name.

Username

A Select field with all the users, where you can choose the user who is going to fill out the survey.

Company Id

Auto-populated field with the company of the selected user.

Status

Select the field with the status of the result with values: In progress, Completed, Expired.

To permit filling out the survey, its status should be “In progress”.


After the result creation, an operator can compile the survey on his own by clicking on the “Fill Out” button at the end of the “Result” record:

In this case, the Result creation and the survey filling from the main survey module are exclusive prerogatives of Deepser internal users.

Default Using

Generally, the survey module relies on the End-User portal, as it allows for the completion of its questions.

Normally, within the email sent during the survey creation phase, a direct link to the portal is included, enabling access to the survey. Upon accessing the survey, a “Result” record is automatically created and associated with the respective survey.

Additionally, it is possible to access the survey management section directly from the End-User portal menu:

NOTE: In the End-User portal, the grids related to the surveys exclusively display records of type “Result”. Therefore, to view a new survey, users are required to go through the email sent during the survey creation phase. Specifically, by clicking on the survey link in the email, the “Result” record will be created and consequently can be viewed in the grid.

By the backend, a user can edit, change, or add a new visualization grid for the survey module in the end-user portal by simply accessing System > Portal > Survey.

Dashboard

The Dashboard entity provides a clear and concise visualization of key data and real-time information about created surveys.

You can access this module from the main menu by navigating to Survey > Dashboard. Alternatively, you can access a Survey Template by clicking on the “Open Dashboard” button in the right top corner:

To access it, you need to select the base template you want to analyze simply by the field in the left top corner (so, all its related surveys will be loaded):

In the Dashboard entity, the survey results are analyzed and filtered based on the questions, also visualized in Charts.

Charts

On the left side of the filters panel, you can set different filters based on which the data displayed on the Charts will change.

 

Submitted At From – To Date fields which you can set a date range from which the results will be filtered based on the date they are submitted.

Company: Multiselect field which filters the results based on the company field.

Username: Multiselect field which filters the results based on the user who submits the results.

Questions

Within the “Questions” tab, it is possible to access the answers related to a specific question. This comprehensive view provides valuable information such as the submission time and the source from which it was submitted, offering insights into the respondent’s identities and the timing of their submissions.

Results

On the results, tab is represented a grid with all the results related to a survey.

Questions: this is a multi-select field that filters results on the grid based on the questions selected.

In the “Results” and “Questions” tabs you can also export data in CSV or XLSX format from the relation grid by using the default exportation button:

Contract and Contract Line

This article includes an overview of the Contract and Contract Line modules, detailing how to manage and track service agreements effectively. It explains how to set up contracts, handle individual contract lines, and ensure all terms and conditions are accurately documented and maintained. This section aims to streamline contract management and provide users with a clear understanding of managing service agreements within the Deepser system.

Contracts and Contract Lines - General Overview

In Deepser, the “Contract” module is used to manage contracts (1) and their associated lines(2).

This management can be done by associating a contract (and line) with a record of other entities, for example:

  • Operations
  • Worklogs – Contract(1), Line(2)

A contract can be associated with multiple lines(1), but a line can only be associated with one contract (2).

Contracts

There are various system automatisms in the “ deep_contract_contract” module to ensure the best management.

Expiration and Renewal

The first automatism relates to the expiration of a contract and its possible renewal.

To make this automatism work, the following fundamental fields are present.

FIELD NAME

DESCRIPTION

NOTE

Expiration Date

Contract expiration date

 

Is Recurring

Flag indicating if the contract is renewable

If it is set to “No,” the contract will not be renewed

Recurring Type

Time Recurrence

 

Recurring Quantity

Amount of temporal recurrence

Field related to “Recurring Type.” If the former is populated to Yearly and this to 2, on the expiration date the contract will be renewed by 2 years

Recurring Increment Percentage

Increment of “Total Amount” field at renewal

If 10% is set and “Total Amount” is at 40000, in the renewed contract the “Total Amount” field will be 44000

Renewed Contract

Populated with the new renewed contract

 

 

There is a System Job, which runs automatically every 2 hours, that performs a check on the expiration of contracts and their possible renewal.

If Job finds a contract with the expiration date less than the current expiration date (1), set the “Expired” field to “Yes” (2).

In addition, if the “Is Recurring” field is valorized to “Yes”, the automatism for renewal is triggered.

The date entered in the “Expiration Date” field is retrieved and, the new contract, is renewed according to the entered timing.

For example, if the date of the expired contract (1) is 09/08/2021 and the recurrence is 2 months, the new contract (2) will automatically have the expiration date set to 09/10/2021.

“Use Groups” field

There is a “Use Groups” field inside the contract, which manages the contract’s visibility within the other modules.

By setting in the “All Groups” field, the contract can be used, for example in tickets, by all users.

If a specific group is set, e.g. “IT – First Level”, all users will have visibility of the contract (if the role/permissions allow), but only users belonging to the specific group will be able to set it in a ticket.

User member of the group 

User not a member of the group

Note: By setting the “Use Contract” field to “No,” the contract will not be visible in other modules select regardless of which group the user belongs to.

Amounts

Within the Contracts form, there is a fieldset called “Amounts.”

Here, the amounts of contracts and related lines are managed.

FIELD NAME

DESCRIPTION

NOTE

Total Amount

Total contract amounts

 

Lines Total Amount

Total amount used in the lines

 

Recurring Lines Amount

Total amount used in recurring lines

 

Non Recurring Lines Amount

Total amount used in non-recurring lines

 

 

This automatism is related to the “Recurring Increment Percentage” field seen in the “Expiration and Renewal” section.

Contract Lines

In the “deep_contract_lines” module there are many system automations, some closely related to contracts.

Expiration and Renewal

As with contracts, there is an automatism regarding the expiration of a line and its possible renewal.

To make this automatism work, the following basic fields are present.

FIELD NAME

DESCRIPTION

NOTE

Expiration Date

Line expiration date

 

Is Recurring

Flag indicating if the line is renewable

If it is set to “No,” the line will not be renewed

Recurring Type

Time Recurrence

 

Recurring Quantity

Quantity of temporal recurrence

Field related to “Recurring Type.” If the first is populated to Yearly and this field to 2, on the expiration date the line will be renewed by 2 years

Recurring Increment Percentage

Increasing the “Total Amount” field at renewal

If 10% is set and “Total Amount” is at 40000, in the renewed line the “Total Amount” field will be 44000

Renewed Contract Line

Populated with the new renewed line

 

 

The System Job that is run (every 2 hours) to check for expiration and possible renewal is the same as for Contracts.

If Job finds a line with the expiration date less than the current date (1), set the “Expired” field to “Yes” (2).

In addition, if the “Is Recurring” field is set to “Yes,” the automatism for renewal is triggered.

The date inserted in the “Expiration Date” field is retrieved and, the new line, is renewed according to the entered timing.

For example, if the expiration date of the expired line(1) is 01/08/2023 and the recurrence is 1 month, the new line(2) will automatically have the expiration date set to 01/09/2023.

“Use Groups” field

Within the line is the “Use Groups” field, which manages the line’s visibility within other modules

By setting in the “All Groups” field, the line can be used, for example in activities, by all users.

If a specific group is set, for example “IT – First Level,” all users will have visibility of the line (if the role/permissions allow), but only users in that specific group will be able to set it in an activity.

User member of the group

User not a member of the group

Note: By setting the “Use Line” field to “No,” the line will not be visible in other forms select regardless of the user’s group.

Lines Billing

Line billing can be done in three different ways:

  • “Generate Invoice” button
  • “Generate Invoice” massive action
  • Automatic Invoicing

NOTE: To be able to bill lines, some fields need to be set in the “Billing” tab.

Field

Description

Note

Product

Product that is billed

 

Product Price

Product price

Populated automatically on product entry

Product Quantity

Quantity of product for the line

Populated automatically on product entry

Product Recurring Type

Temporal recurrence of the product

 

Product Recurring Quantity

Recurrence of the quantity (temporal) of the product

Related to the “Product Recurring Type” field.

Billing Recurring Type

Type of recurrence

 

Billing Recurring Quantity

Quantity of billing recurrence

 

Billing Last Date

Last billing date

 

 

 “Generate Invoice” Button

If the fields are populated correctly, after saving the line, the “Generate Invoice” button will appear

Mass Action “Generate Invoice”

From the grid of lines, if mass actions are active, it will be possible to mass-bill different lines from different contracts.

To mass invoice, as a first step, you need to select the lines of interest (1).

Next, in the list of mass actions (2) choose “Generate Invoice” and press the “Submit” button.

Automatic Billing

There is a job in the system that bills the lines every day at 04:00.

If the billing was successful, regardless of the chosen mode, you will be able to view the created invoice from the Contract (or directly from the sales_invoice module).

Contract Creation

To create a new contract on Deepser, you need to open the Contracts form.

On the screen that will open, press the “Add Contract” button.

When the button is pressed, a floating window will appear asking you to select the contract type before proceeding with creation.

Once the type has been selected and “New” has been pressed, the following screen will open.

TAB

FIELD

DESCRIPTION

NOTE

CONTRACT

 

 

 

 

Contract Number

 

 

 

Name

 

 

 

Status

 

 

 

Use Contract

Field used for visibility management

If set to “No” the contract will not be selectable in the other forms

 

Use Groups

Field used for managing visibility limited to groups

If set to “No” the contract will not be selectable in the other forms

 

Description

 

 

 

Total Amount

 

 

 

Contract Lines

Grid showing the lines linked to the contract

 

DATES

 

 

 

 

Signing Date

 

 

 

Start Date

 

 

 

Delivery Date

 

 

 

Cancellation Date

 

 

 

Expiration Date

 

 

 

Is Recurring

 

Field used for managing renewals

USERS

 

 

 

 

Customer Company

 

 

 

Supplier Company

 

 

 

Vendor

 

 

 

Owner Company

 

 

 

Owner Group

 

 

 

Owner User

 

 

 

Assigned Company

 

 

 

Assigned Group

 

 

 

Assigned User

 

 

BILLING

 

 

 

 

Billing Mode

 

Field used for billing

 

Billing Recurring Type

 

Field used for billing

 

Billing Recurring Quantity

 

Field used for billing

 

Payment Condition

 

Select containing the values in the form of the same name

 

Price List

 

Select containing the values in the form of the same name

 

Billing Last Date

 

Field used for billing

 

Billing Next Date

 

Field used for billing

 

Invoices

Grid containing invoices related to the contract

 

ACTIVITY/ATTACHMENTS

 

 

 

 

Activity

Comments and worklogs related to the contract

 

 

Tasks

Task related to the contract

 

 

Attachments

Attachments related to the contract

 

Line Creation

To create a line in Deepser there are two ways:

  • From the Contract
  • From the model “deep_contract_line”

Creation from Contract

To create a line from the Contract, you will need to move to the “Contract lines” field and press the “Add Line” button.

On the side, a pre-populated floating window will open with some data.

Creation from the Lines module

To create the line directly from the module, you will need to move inside the line form.

From the module, press the “Add Line” button.

The form that will open will not be pre-filled, different from creating the line from the contract.

Tab

Field

Description

Note

Line

 

 

 

 

Contract

Contract to which the line is related

 

 

Line Type

Line type

 

 

Name

 

 

 

Status

 

 

 

Use Line

 

 

 

Use Groups

 

 

 

Start Date

 

 

 

Expiration Date

Line expiration date

 

 

Is Recurring

Flag indicating if the line is renewable

If it is set to “No,” the line will not be renewed

 

Recurring Type

Time Recurrence

 

 

Recurring Quantity

Quantity of temporal recurrence

Field related to “Recurring Type.” If the first is populated to Yearly and the second to 2, on the expiration date the line will be renewed by 2 years

 

Recurring Increment Percentage

Increasing the “Total Amount” field at renewal

If 10% is set and “Total Amount” is at 40000, in the renewed line the “Total Amount” field will be 44000

 

Renewed Contract Line

Populated with the new renewed line

 

 

Calculation Type

Select with values: None, Time, Quantity

 

 

Total Time

Total line time

 

 

Spent Time

Time spent of the line

Calculation Type = Time

 

Remaining Time

Remaining line time

Calculation Type = Time

 

Total Quantity

Total line quantity

Calculation Type = Quantity

 

Spent Quantity

Quantity used of the line

Calculation Type = Quantity

 

Remaining Quantity

Remaining quantity of the line

Calculation Type = Quantity

Billing

 

 

 

 

Product

Product that is billed

 

 

Product Price

Product price

Visible only if a product is selected

 

Product Quantity

Quantity of product for the line

Visible only if a product is selected

 

Product Sku

 

Visible only if a product is selected

 

Product Name

 

Visible only if a product is selected

 

Price List

 

Visible only if a product is selected

 

Product Recurring Quantity

Recurrence of the quantity (temporal) of the product

Visible only if a product is selected

 

Product Recurring Type

Temporal recurrence of the product

Visible only if a product is selected

 

Billing Mode

 

 

 

Billing Recurring Type

Type of recurrence

 

 

Billing Recurring Quantity

Quantity of billing recurrence

Related to the “Billing Recurring Type” field.

 

Billing Last Date

 

Fundamental to billing

 

Billing Next Date

 

 

Associate a Contract / Line with other entities

Contracts and lines, principally, are associated with Operations and worklog, but with custom configuration they can be associated with all modules in Deepser.

Operation

Within the Operations form is the “Contract” field.

It is particularly useful, in reporting, exports and for applying filters (e.g., grids).

Worklog

In the worklog form there are the fields: “Contract” and “Contract Line.”

These fields, in addition to being informative, are necessary for billing the worklog related to the contract.

Also, from the activity it is possible to scale the time or quantity used from the line total. Within the Lines form, there is a fieldset called “Line Calculation.”

Here, the calculation of Lines is managed.

FIELD NAME

DESCRIPTION

NOTE

Calculation Type

Select with values: None, Time, Quantity

 

Total Time

Total line time

Calculation Type = Time

Spent Time

Time spent of the line

Calculation Type = Time

Remaining Time

Remaining line time

Calculation Type = Time

Total Quantity

Total line quantity

Calculation Type = Quantity

Spent Quantity

Quantity used of the line

Calculation Type = Quantity

Remaining Quantity

Remaining quantity of the line

Calculation Type = Quantity

 

Note: If the “Calculation Type” field is populated to “None” and “Total Quantity” to “10”, the quantity will not be scaled.

Calculation Type “Time”

By setting the field to “Time,” it will be necessary to value the “Total Time” field.

The time will be scaled when inserting, for example, an activity into an operation.

To scale it, it will be necessary to value the “Contract,” “Contract Line,” and “Duration” fields

When the Activity is saved, the time fields will be updated.

Calculation Type “Quantity”

By setting the field to “Quantity,” it will be necessary to value the “Total Quantity” field.

The quantity used will be scaled when inserting, for example, an activity into an operation.

To scale it, you will need to value the “Contract,” “Contract Line,” and “Contract Line Quantity” fields.

When the Activity is saved, the quantity fields will be updated.

Contract Type

The contract type is used for better contract management and classification. In addition, from the configuration of types, it will be possible to limit their visibility through groups.

The typologies are visible in the module menu.

To create a new type, you need to go to System (1) > Contract Configuration (2) > Type (3).

On the screen that will open, click the “Add Type” button.

Below is a description of the fields in the form.

Field

Description

Note

Name

Type name

 

Position

Position in the menu

 

Status

Whether the type is enabled or disabled

If disabled, the type will not be visible in the menu

Icon

 

 

Enabled Groups

Type-enabled groups

 

Menu Visibility Groups

Groups enabled to display the type in the menu

 

Increment Prefix

Automatic prefix

By setting “Hourly -” as the prefix and “- 2024” as the suffix, the contract number will automatically be set to “Hourly – 1- 2024.” 1 will be autoincremented (“Increment Id” field).

Increment Suffix

Automatic suffix

Increment Id

 

 

Description

 

 

Line Type

The line type is used for better line management and classification. In addition, from the type configuration, it will be possible to restrict its visibility through groups.

To create a new type, you need to go to System (1) > Contract Configuration (2) > Line Type (3).

On the screen that will open, click the “Add Line Type” button.

Below is a description of the fields in the form.

Field

Description

Note

Name

Type Line name

 

Position

Position in the select

 

Status

Whether the type is enabled or disabled

If disabled, the type will not be visible in the select

Icon

 

 

Enabled Groups

Type-enabled groups

 

Description

 

 

Contracts and Escalation Rules

Using escalation rules, it is possible to set up, for example, the sending of a notification that a contract will expire soon.

Below we will see how to configure the alert in detail.

Template Email

As a first step, let’s proceed with the creation of a new email template.

To create the new template, you need to follow the following path: System > Tools (1)> Email (2)> Templates (3).

On the screen that will open, press the “Add Mail Template” button.

On the screen that will open immediately afterwards you will need to fill in the fields as indicated:

Field

Value

Note

Name

Alert contract expiration

Can be changed

Code

alert_contract_expiration

Can be changed

Status

Enabled

 

Subject:

				
					<?php
$contract = $this->getModel();
$customerName = Deep::getModel('deep_company/company')->load($contract->getCustomerCompanyId())->getName();
$nrContratto = $contract->getContractNumber();
$expirationDate = new Zend_Date(Deep::helper('deep_calendar')->convertDateToUserTimezone($contract->getExpirationDate(), Mage::app()->getLocale()->getDateTimeFormat(Mage_Core_Model_Locale::FORMAT_TYPE_SHORT), Deep::app()->getLocale()->getLocale()));
$expiringDate = $expirationDate->get('dd/MM/YYYY');
?>
<?php echo $customerName." - ". Deep::helper('deep_email')->__('Contract Nr.').$nrContratto." - ".Deep::helper('deep_email')->__('expiring on:')." ".$expiringDate; ?>

				
			

Body:

				
					<?php 
$contract = $this->getModel();
$nomeContratto = $contract->getName();
$nrContratto = $contract->getContractNumber();
$expiringDate=new DateTime();
$expiringDate=$expiringDate->createFromFormat('Y-m-d H:i:s',$contract->getExpirationDate());
$expiringDate->setTimezone(new DateTimeZone('Europe/Rome'));
$expiringDate=$expiringDate->format('d/m/Y');
$url = Deep::getUrl('adminhtml/contract_contract/edit', ['id' => $contract->getId()]);
?>
<?php $this->includeTemplate("sedoc_header") ?>
<!-- Start of Main Content -->
<tr style="">
    <td bgcolor="#FFFFFF" align="center" style="">
        <table width="100%" align="center" cellpadding="0" cellspacing="0" border="0" class="devicewidth" style="">
            <tbody style="">
            <!-- Start Spacer -->
            <tr>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="h26" height="36" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- End Spacer -->
            <tr style="">
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="mktEditable content mktEditable content" id="edit_text_1" valign="middle" style="font-family:Calibri, Helvetica, sans-serif; font-size:16px; color:#505050; text-align:left; line-height:25.6px; font-weight:normal; text-transform:none;">
                    <p>
                        <br>
                        <?php echo Deep::helper('deep_email')->__('The contract number')?> <b style="font-weight: 700;"><a href="<?php echo $url ?>"><?php echo $nrContratto ?></a></b> - <?php echo $nomeContratto; ?> 
                       <?php echo Deep::helper('deep_email')->__('expires on:')?> <?php echo $expiringDate; ?><br>
                        <br>
                    </p>
                </td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- Start Spacer -->
            <tr>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td height="30" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- End Spacer -->
            </tbody>
        </table> 
    </td>
</tr>
<!-- End of Main Content -->
<!-- End of Main Content -->
<?php $url = Deep::getUrl('adminhtml/contract_contract/edit', ['id' => $contract->getId()]); ?>
<!-- start of Button -->
<tr style="">
    <td bgcolor="#FFFFFF" align="center" class="mktEditable" id="edit_cta_button" style="">
        <table width="100%" border="0" cellspacing="0" cellpadding="0">
            <tbody>
            <tr>
                <td class="w22" width="41" style="font-size: 1px; line-height: 1px;">&nbsp;</td>
                <td align="left">
                    <table class="button" cellpadding="0" cellspacing="0" border="0" align="left" bgcolor="#0080ff" style="-webkit-border-radius: 4px; -moz-border-radius: 4px; border-radius: 4px;">
                        <tbody>
                        <tr>
                            <td width="518" align="center" valign="middle" height="65">
                                <span style="color: #ffffff; text-decoration: none;">
<a class="mobButton mktNoTok" href="<?php echo $url ?>" style="font-family: Calibri, Helvetica, sans-serif; font-size: 16px; color: #ffffff; display: block; height: 65px; mso-                 line-height-rule: exactly; line-height: 65px; font-weight: normal; text-decoration: none; text-align: center!important;" target="_blank" title="Link al ticket">
		Go to the Contract
	</a>
	</span>
                            </td>
                        </tr>
                        </tbody>
                    </table> </td>
                <td class="w22" width="41" style="font-size: 1px; line-height: 1px;">&nbsp;</td>
            </tr>
            </tbody>
        </table>
    </td>
</tr>
<!-- end of Button -->
<?php $this->includeTemplate("footer") ?>

				
			

Escalation Rule

To create the Escalation rule, the following path must be followed: System (1)> Service Configuration (2)> Escalation Rules (3).

On the screen that will appear, press the “Add Rule” button.

On the screen that opens, fill in the data as indicated below.

Field

Value

Note

Name

Contract expiration

Can be changed

Model Alias

DeepContract – Contract

 

Email Event

 

To be filled in later, after the creation of the event

Level

0

Can be changed. For more info press here

Next Level

1

Can be changed. For more info press here

Cron Expression

0 * * * *

Every hour

Status

Enabled

 

    

After filling in the fields, press the “Apply” button.

Once saved, query-builders will appear. You will need to set the filters as follows:

The filters set are as follows:

  • Expiration Date less date after now 30,0,0 à 30 days left before the contract expires.
  • Expired equal 0 à The contract has not expired.

Email Event

To create the new event, which will later be linked to the Escalation rule, you need to follow the following path: System > Tools (1)> Email (2)> Event(3).

On the screen that will appear, press the “Add Event” button.

Below are the values to be entered in the required fields:

Field

Value

Note

Name

Alert contract expiration

Can be changed

Status

Enabled

 

Email Template

Alert contract expiration – [alert_contract_expiration]

Field that corresponds to the previously created template

Model

DeepContract – Contact

 

Event Expression:

				
					if($this->getModel()->getExpirationDate()){
    if($this->getModel()->getId() && $this->getModel()->getData('escalation_rule') && $this->getModel()->getData('escalation_rule')['entity_id'] == 3){
        return true;
    }
    return false;
}
return false;

				
			

Note: “3” represents the ID of the escalation rule

To:

				
					$this->addTo('mail.test@mail.com');
				
			

Note: ‘mail.test@mail.com’ is to be replaced with the email address to be notified.

 

Once all the fields are filled in, you will need to save the event by pressing the “Apply” or “Save” button.

Next, we reopen the escalation rule created earlier to set up the newly created event.

Report Documentation

Report Module in Deepser is used to extract data from various other models such as Operation, Ci, contracts. Report can be configured to extract data in .PDF or .XLS format. To maintain a more systematic arrangement for reports, you can use “Folders” to categorize them.  

In the following article you can found: 

  • Report Configuration: Which can be managed by an administrator user. 
  • Report Usage: Which describes the usage for a non-administrator user. 

Report Configuration

Within the report configuration, an admin user can: 

  • Create a custom folder 
  • Create an executable report 
  • Schedule a report for automatic delivery to one or more users 

 Folder Creation 

To create a new folder for your reports, you can go to “System->Report->Folder”. On the folders grid you can see all the previously created folders. 

By clicking on Add Folder button, the following screen will appear:

Below is a description of the available fields: 

Field 

Description 

Name 

Folder’s name 

Code 

This field is used to uniquely identify a folder. It is best  

Position 

This field indicates the position and listing of this folder on the grid. 

Icon 

On this field you can use an image as icon for the folder. 

Enabled Groups 

This field is used to limit visibility of users that can have access to this folder. 

Status 

Select field that is used to enable or disable the folder. 

Report Creation 

To configure a new report, you should go under “System->Report->Report”.  

You can now see the reports grid and the “Add Report” button, when you click on it you can create a new report.

By clicking on Add Report button the following screen will appear: 

Below is a description of available fields: 

Field 

Description 

Name 

Report Name 

Code 

Report’s code field is used to identify the report with a unique string. Utilizing a single string for this purpose is considered the most effective approach. 

Library 

Field of select type where you choose the type of report PDF, XLS and CVS. 

Folder 

Select field where select the destination folder for placing this report. 

CSV Delimiter  

This field is only visible if the library is ‘CSV’. Delimiter field can be populated by a character  such as ‘ ; ’ or ‘ , ’  which will be used as a separator between file records. 

CSV Enclosure  

This field is only visible if library is ‘CSV’. 

CSV enclosure field is used to define the enclosing characters of each record, for example double or single quotes. 

Form Render Expression 

The initial stage in setting up a report involves configuring Form Render Expression. On this field you can configure all the Filters based on which data will be extracted from the report. This field is configured in the same way for both: PDF and Excel report. 

To add the filters the following custom code is used:  

				
					// Firstly it is retrieved type values array. This values will be used as options on the filter field.
$type = Deep::helper('deep_service/type')->typeToOptionArray();
$this->addField(
            'type_id', // this indicates the filter field code, which has to be unique for each field
            'select', // filter field type, in this case its select, but it can also be text, date
            array(
                'label' => Deep::helper('deep_service')->__('Type'), // Label of the filter field
                'multiple' => 'multiple', // In fields of type select you can add this parameter if you want to select multiple choices for this    //filter
                'values' => $type,  // If field is of type select you also need to provide the option values that can be selected from this field. // The given value for this parameter should be of type array. In this case the given value is an array with all the service types.
                'columns' =>1 // This field indicates the width of this field on the report fieldset.
            )
        );
$this->addField(
            'created_at_from',
            'date',
            array(
                'label' => Deep::helper('deep_service')->__('(Created Date) From'),
                'image' => $this->getSkinUrl('images/grid-cal.png'),
                'time' => true,  // this parameter indicates whether you want to display also the time on this field.
// with format parameter you set the format of the date. In this case the given value gives a format date based on the //current user Local time zone.
                'format'  => Mage::app()->getLocale()->getDateTimeFormat(Mage_Core_Model_Locale::FORMAT_TYPE_SHORT),
                'columns' =>1,
            )
    );
$this->addField(
            'created_at_to',
            'date',
            array(
                'label' => Deep::helper('deep_service')->__('(Created Date) To'),
                'image' => $this->getSkinUrl('images/grid-cal.png'),
                'time' => true,
                'format'  => Mage::app()->getLocale()->getDateTimeFormat(Mage_Core_Model_Locale::FORMAT_TYPE_SHORT),
                'columns' =>1,   ));
				
			

After the configuration of form render expression is finished you can click on the “Preview” button, to see all the filters created. An example PDF report is shown below where there are extracted tickets filtered by type and creation date. 

Here is the preview of report filters: 

Then to extract the report based on these filters, you can click on the “Run” button on the right corner. 

NOTE: If the “Before Run Expression” or “Run Expression” script is not correct, the report will not run. 
 

Before Run Expression 

Before Run Expression is used to filter the collection that will be shown on the report, by using the filter fields configured on the “Form Render Expression”. 

On the first line the PDF library is initialized by setting the paper format and orientation. 

The following code iterates through each filter field and filters the collection based on those. Then the variable assigned with the operation collection is set to the report object. 

				
					// PDF library is initialized by setting the paper format and orientation.
$this->loadLibraryObj()->setPaper('A4', 'landscape'); 
$filters = $this->getFormData(); // Retrieve all the filters from Form Render Expression
// Retrieve the operation collection
$collection = Deep::getResourceModel('deep_service/operation_collection'); 
// Iterate through each filter field and filter the collection based on those. 
if ($filters['created_at_from'] !='') 
        {
             $collection->addFieldToFilter( 'main_table.created_at', [ 'gt' => 
            Deep::helper('deep_calendar')->filterDateTime($value) ] );
        }
        
        if ($filters['created_at_to']) 
        { 
$collection->addFieldToFilter( 'main_table.created_at', [ 'lt' => 
Deep::helper('deep_calendar')->filterDateTime($value) ] );
        }
  
        if ($filters['type_id'] !='') {
            $collection->addFieldToFilter( 'main_table.type_id', [ 'in' => $value ] );
        } 
// Then the variable assigned with the operation collection is set to the report object.
 
$this->setData('operation_collection',$collection);
				
			

Run Expression 

The run Expression Field is used to configure the layout structure of the report as well as retrieve all the records from the “Before Run Expression” field and display them on the report. On case of a PDF report, you can write html code to create tables and styles for it and Php code to retrieve all the needed values that are to be shown. 

When the report is of type PDF here is the example of it: On the first part of the code there are some styles to format the page structure and also the table that will display the operation data. 

				
					<!DOCTYPE html>
<html>
<head>
    <style>
        /** Define the margins of the page and the font **/
        @page {
            margin: 70px 25px;
font-family: Helvetica;
font-size: 12px;
        }
            /** Define the header style */
            header {
                position: fixed;
                top: -70px;
                left: 0px;
                right: 0px;
                height: 50px;
                color: grey;
                text-align: center;
                line-height: 35px;
	font-size: 18px;
            }
            footer {
                position: fixed; 
                bottom: -70px; 
                left: 0px; 
                right: 0px;
                height: 50px;
                
                /** Extra personal styles **/
                color: grey;
                text-align: center;
                line-height: 35px;
	font-size: 12px;
            }
            
            #report-title{
text-align: center;
}
 
 #report-title{
text-align: center;
}
#report-table {
border-collapse: collapse;
width: 100%;
	}
#report-table td, #report-table th {	
    border: 1px solid #ddd;		
    padding: 8px;
			}
#report-table tr:nth-child(even){
    background-color: #f2f2f2;
			}
#report-table th {		
    padding-top: 12px;	
    padding-bottom: 12px;	
    text-align: left;	
    background-color: #D90C0C;	
    color: white;
			}
   
    </style>
    
  <?php
        // get the report name
        $reportName = $this->getName();
        // collection of operation to be later used on the table
        $collection = $this->getData('collection');
// map the  fields that are to be shown on the table of operation records
        $fields = [
            'entity_id'=>'Id',
            'type_id'=>'Service Type',
            'title'=>'Title',
            'requester_username'=>'Requester User',
            'status'=>'Status',
        ];
// retrieve the status List values 
$statusList = Deep::helper('deep_list')->loadListValues(Deep_Service_Model_Operation::LIST_CODE_STATUS)->toOptionHash();
    ?>
<title><?php echo Deep::helper('deep_report')->__($reportName); ?>

<title><?php echo Deep::helper('deep_report')->__($reportName); ?></title>
</head>
<body>
    <script type="text/php">
        if ( isset($pdf) ) {
            $x = 800; // position on y 
            $y = 580; // position on x 
            $text = "{PAGE_NUM} / {PAGE_COUNT}";
            $font = $fontMetrics->get_font("helvetica", "bold"); // document’s font
            $size = 8; 
            $color = array(0,0,0);
            $word_space = 0.0;  //  default
            $char_space = 0.0;  //  default
            $angle = 0.0;   //  default
// add page numbers (in the format of "{PAGE_NUM} / {PAGE_COUNT}") to the generated PDF 
// document at the specified position using the specified font and styling
            $pdf->page_text($x, $y, $text, $font, $size, $color, $word_space, $char_space, $angle);
        }
    </script>
<!-- document’s header -->
    <header>
        <?php echo Deep::helper('deep_report')->__($reportName); 
        ?>
    </header>
    
<?php 
if (!$collection || $collection->count() == 0){
    echo "No data found";
    return;}?>
<!-- table that shows the operations-->
<table id="report-table" style="page-break-inside: auto;">
    <thead><tr><?php foreach ($fields as $field => $value): ?>
    	<th><?php echo Deep::helper('deep_service')->__($value); ?></th>
    	<?php endforeach; ?>
    	</tr></thead>
<!-- iterate through all the operations and add each record as a table row  -->
<?php foreach ($collection as $operation): ?>
	<tr>    <?php foreach ($fields as $field => $value): ?>
<td>   <?php 
		    if($field =='requester_username') // Retrieve the requester Name And Surname
		    {$value = Deep::getModel('deep_admin/user')->load($operation->getData($field),'username')->getId()  ? Deep::getModel('deep_admin/user')->load($operation->getData($field),'username')->getName() :''  ;
		    }else if($field == 'status')
		    {
		        $value = $statusList[$operation->getData($field)]; // Retrieve status Value Label
		    }else if($field == 'type_id') 
		    {
     $value = Deep::getModel('deep_service/type')->load($operation->getData($field))->getId() ? Deep::getModel('deep_service/type')->load($operation->getData($field))->getName() :'' ;
		    }else{
		        $value = $operation->getData($field);
		    }
		        echo $value;
		    ?>
		    </td>	    
<?php endforeach; ?>
</tr>
<?php endforeach; ?>
 
</table>
</body>

  <!-- Report’s footer -->
    <footer class="footer">
        <?php echo Deep::helper('deep_report')->__('Powered by DeepDesk'); ?>
        <span class="page-number">Page </span>
    </footer>
				
			

Scheduled Report 

 Scheduled Reports are reports that are sent by email periodically through a cron expression. To configure a scheduled report you should go under “System->Report-> Scheduled Report” and click on the ‘Add Scheduled Report’ button. 

By clicking on “Add Scheduled Report” button you can create a scheduled report. 

Below there is an example of a scheduled report that sends an email with the Invoice Report attached, every first day of the month. 

Below is a description of the available fields: 

Field 

Description 

Name 

With this field you can set the Scheduled Report’s name. 

Report 

Select field where you can select a configured report that will be used as the scheduled report. 

Cron Expression 

On this field you can set the time period on which the report will be sent. 

Send To 

Text field where you can set the email addresses divided by ‘;’ that will receive the report. 

Message Subject 

Custom code expression field where you can set the email subject in html format, the same format used as in email template. 

Message Body 

Custom code expression field where you can set the email message body in html format, the same format used as in email template. 

Mailbox Id 

Select field where you can choose the mailbox from which the email will be sent. 

Email Template 

Select field where you can choose the email template that will be used for this email. When selecting an email template, the ‘message subject’ and ‘message body’ fields will be ignored. 

Status 

With this field you can ‘enable’ or ‘disable’ the scheduled report. 

Report Usage

As a non-administrator user, you can proceed with: 

  • Access a folder to view the reports within it.  
  • Execute a Report. 
  • View the history of executed reports. 

When clicking in one of the folders, you will be able to access all the reports part of that folder. By clicking on the ‘Run’ button, you can generate the corresponding report. 

Report History 

Through report history section you can have a look at all the report executions with details like timestamp of when it was run, who was run by and execution duration. 

Below is a description of the available buttons: 

  • Delete: by clicking “Delete” button you can delete the report execution record. (You can’t delete the report record from here). 
  • Download: download the generated report from this execution. 
  • Run: Re-Run the report that was executed. 

Sales

The Sales Module in Deepser provides tools for managing customer interactions and tracking sales opportunities. It centralizes sales activities, allowing users to organize leads, monitor progress, and manage workflows. The module integrates with other components of the system, offering real-time insights and facilitating seamless transitions between different stages of the sales process. This functionality supports efficient sales management and helps in maintaining comprehensive records of customer interactions and transactions.

Catalog and Price List Overview

The Catalog module in Deepser identifies a macrocategory composed of the following entities

  • Product: here you can create, maintain, and store products
  • Price Lists: here you can manage and set up different price lists.

The entities in question, once configured and registered in Deepser, can then be used within the modules that require their use, such as Quotes, Invoices, Orders, Contract Lines. 

Catalog Configurations

The Catalog module allows the configuration and management of different types of products and price lists. 

The responsibility for these configurations falls on the administrator users, who can access the section dedicated to the configuration from System > Catalog Configuration

Product Type Configuration

By clicking to configure the product types, we will then be able to define a product type to differentiate the different nature of the products (for example Physical Products, Training Services, etc.)

Accessing the list of product types, either by clicking on the “+ Add Product Type” creation button or by modifying an already existing type, the following screen will appear:

Below is the list of available fields and their meaning:

Field

Description

Name

This field indicates the name of the product type.

Position

It is used to indicate the viewing position within the Deepser Catalog menu.

Description

Descriptive field

Icon

Through this field it is possible to associate an icon with the product type

Groups

Identify which groups have access to the product type from the backend

Portal Groups

Identify which groups have access to the product type from end-user portal

Groups Menu Visibility

By specifying one or more groups in this field, you allow them the possibility of viewing the product type item in the Catalog menu.

Frontend Visibility

With this flag you can enable the availability of the product type within the fronted portal (portal for non-registered users)

Status

Through this field, you can decide whether to enable or disable a product type.

Price List Type Configuration

By clicking to configure the types of price lists, either by modifying an existing type or by creating a new one, the following screen will appear:

Below is the list of available fields and their meaning:

Field

Description

Name

This field indicates the name of the price list type.

Position

It is used to indicate the viewing position within the Deepser Catalog menu.

Description

Descriptive field

Icon

Through this field it is possible to associate an icon with the type of price list

Groups

Identify which groups have access to the price list type from the backend

Portal Groups

Identify which groups have access to the price list type from end-user portal

Groups Menu Visibility

By specifying one or more groups in this field, you allow them the possibility of viewing the price list type item in the Catalog menu.

Frontend Visibility

With this flag you can enable the availability of the type of price list within the fronted portal (portal for unregistered users)

Status

Through this field, you can decide whether to enable or disable a type of price list.

Incremental Prefix

Using this field, you can configure a prefix to be applied in price list numbering. (It is used to enhance the Incremental ID field present in the price list main data).

Incremental Suffix

Using this field, you can configure a suffix to be applied in the price list numbering. (It is used to enhance the Incremental ID field present in the price list main data).

Incremental ID

Using this field, you can configure an ID to be applied in the price list numbering. (It is used to enhance the Incremental ID field present in the price list main data).

Incremental Padding Font

Using this field, you can configure a padding character to be applied in the price list numbering. (It is used to enhance the Incremental ID field present in the price list main data).

Incremental Padding Length

Using this field, you can configure the length of the padding to be applied in the price list numbering. (It is used to enhance the Incremental ID field present in the price list main data).

Product

After configuring the types, you can proceed with inserting a product.

To access the list of products, from the main menu Catalog > Product, we can select the “All” item (which will contain the list of all the products registered in the system, of any type) or you can select the item corresponding to one of the types of configured product.

To create a new product, you can click on “+ Add Product” button on top right corner.

The following fields will then be available to fill in on the entry screen:

Main Data

Field 

Description 

Name 

Text field that is populated with product name 

Sku 

Text field that has the unique code for the product 

Weight 

Text field of type number that indicates the weight of product 

Description 

Product description 

Class 

Select field that indicates the type of product, which can be: simple or grouped. When a product is defined as “grouped” all the other created products will be linked to this product. 

The grouped products are mainly used in the “Sales” modules of the CRM section (Offers, Orders, Invoices) where they can be used dynamically to add products to an invoice by selecting a single grouped product or statically to add a set of products with the selection of a single grouped product. 

Status 

Select field that indicates that whether a product is enabled or disabled. 

Category 

Category field type that shows all the categories configured for product model. 

Price

Field

Description

Currency

Select field with all the available configured currencies. To configure currencies, you can go on:
System -> Configuration -> General-> Currency Setup.

Price

Price field that shows the regular price and is measured by the selected currency.

Special Price

This field indicates a price that can be offered for a designated time period. During the specified time period, the special price appears instead of the regular price.

Special Price From

The start date of when the special price starts to apply.

Special Price To

The end date of the special price application.

Maximum Retail Price

On this field you can set the maximum manufacturer’s retail price.

Manufacturer’s Suggested Retail Price

On this field you can set manufacturer’s suggested retail price, which gives you the ability to remain in compliance with the manufacturer’s requirements.

Linked Products

On this tab are shown all the products that are linked to this product. The field of this tab is populated with the products grid when a product is defined as “grouped”.

Invoice Quantity Rules

On this tab you can set Invoice rules for the product. By invoice rule you can set the quantity of this product that you want to be invoiced.

So, you can proceed clicking on “+ Add Invoice Rule” button on the Invoice Rules grid:

The following fields will then be available to fill in on the entry screen:

Field

Description

Product

Select field which is auto populated with current product’s name.

Model Alias

Select field where you can choose the model on which you want this rule to apply to.

Quantity Calculation Mode

Select field which is used to set whether the quantity for this rule will be set by a field present in the model or by a fixed value.

Quantity Model Field

Select field which indicates the quantity for which this rule will be applied.

Model Expression

This query Builder field sets a filter on the model on which this rule will apply to.

Invoice Expression

This query Builder field sets a filter on the invoices on which this rule will apply to.

Priority

Text field that sets the priority that determines the order in which multiple rules are applied. When you have multiple price list rules that could potentially apply to a product, Deepser applies them based on their priority.

Status

Select field that indicates that a rule can enabled or disabled.

Price List

Price Lists in Deepser are used to create customized price rules according to products, minimum quantity and minimum price.

The following fields will then be available to fill in on the entry screen:

Main Data

Field

Description

Name

Text field that will be populated with price list’s name

Code

Text field that is unique for every pricelist

Status

Select field that indicates that a pricelist can be enabled or disabled. 

Apply to all Accounts

Checkbox field that is used to set this pricelist to all the Accounts present in Deepser, when toggled to “YES”, or you can decide to choose some specific accounts that this pricelist will apply to.

Priority

This field is used to determine the priority of the price lists when multiple price lists are applicable to an account. This field is used to resolve conflicts between price lists and determine which one takes precedence.

Start Date

Datetime field that is used to set the start date from when this price list will be available.

End Date

Datetime field that is used to set the end date of this pricelist application.

 

Rules

Price List Rules allow you to create discounts and special pricing based on various conditions.

Field

Description

Name

Text field that will be populated with rules name.

Priority

Text field that sets the priority that determines the order in which multiple rules are applied. When you have multiple price list rules that could potentially apply to a product, Deepser applies them based on their priority.

Status

Select field that indicates that a rule can enabled or disabled.

Product Class

Select field which is used to set the class of product that this rule will apply to.

Price Change Mode

Select field that sets the mode by which this rule will be applied by which can be: percent, fixed or amount.

Percent: It is used to apply a percentage discount via rule.

Fixed: Used to apply a fixed amount of price via rule.

Amount: It is used to directly modify the value of the product within the reference document on which the rule is applied.

Value

The value of discount that will be applied to the products, this value can be measured as percentage or as a fixed number.

Product Expression

By this query builder field you can set some filters on the products you want this rule to apply to.

Billing Overview

In this article we will look specifically at how billing works for the different modules in Deepser.

Some modules have automatic product automations, while others require a minimum of customization.

Usually, the correct flow used for invoicing is Quote -> Order -> Invoice, but there may also be instances where other entities need to be invoiced.

Below we will look at the most frequently used modules for billing:

  • Orders (DeepSales – Order)
  • Contracts / Lines (DeepContract – Contract / DeepContract – Line)
  • Worklog (DeepActivity – Activity)
  • Movements (DeepInventory – Movements)

In addition, it will be explained step by step how to bill, with custom code, a single operation.

The generated invoices will then be viewable in the dedicated form, which can be reached with the following path: Crm (1) > Sales (2) > Invoices (3) > All (4).

Order Billing

To bill a specific order, it is necessary to move to the dedicated module.

Crm (1) > Sales (2) > Orders (3) > All (4).

On the screen that will appear, open the order you intend to invoice.

On the top right inside of the order there is an “Invoice” button.

Pressing it will generate the automatically filled invoice based on the data entered in the order.

Lines Billing

Line billing can be done in three different ways:

  • “Generate Invoice” button
  • “Generate Invoice” massive action
  • Automatic Invoicing

NOTE: To be able to bill lines, some fields need to be set in the “Billing” tab.

Field

Description

Note

Product

Product that is billed

 

Product Price

Product price

Populated automatically on product entry

Product Quantity

Quantity of product for the line

Populated automatically on product entry

Product Recurring Type

Temporal recurrence of the product

 

Product Recurring Quantity

Recurrence of the quantity (temporal) of the product

Related to the “Product Recurring Type” field.

Billing Recurring Type

Type of recurrence

 

Billing Recurring Quantity

Quantity of billing recurrence

 

Billing Last Date

Last billing date

 

“Generate Invoice” Button

If the fields are populated correctly, after saving the line, the “Generate Invoice” button will appear

Mass Action “Generate Invoice”

From the grid of lines, if mass actions are active, it will be possible to mass-bill different lines from different contracts.

To mass invoice, as a first step, you need to select the lines of interest (1).

Next, in the list of mass actions (2) choose “Generate Invoice” and press the “Submit” button.

Automatic Invoicing

There is a job in the system that bills the lines every day at 04:00.

If the billing was successful, regardless of the chosen mode, you will be able to view the created invoice from the Contract (or directly from the sales_invoice module).

Worklogs Billing

To bill activities related to operations, you must create the invoice directly from the DeepSales – Invoice module and select the invoice type.

On the screen that opens you will need to fill in the basic fields as described below:

Field

Value

Note

Account

 

Account to be billed for the operation

Name

 

Invoice name

Status

Enabled

 

Model Alias

DeepService – Operation

Fundamental field for selecting activities

Model ID

 

Fundamental field for selecting activities.

It corresponds to the ID of the operation

Once you have filled in the fields and pressed the “Apply” button, you will need to move to the “Activities and Movements” tab (1) to select the activities to be billed.

Next, to view the worklogs linked to the operation, press the “Add Activity” button (2).

After pressing the button, a floating window will open containing the activities we can bill.

These are filtered according to the ID entered in the “Model ID” field of the invoice.

Flagging the worklogs of interest (1) will allow them to be added to the invoice via the “Add”(2) mass action.

Once the “Submit” button is pressed, the worklogs will be added to the invoice.

Movements Billing

To invoice the movements of a ticket, a custom field of element type “Inventorymovementgrid” must be added to the operations form.

For more information regarding the creation of custom fields click here.

In the “Extra” Tab we are going to set the “Default Grid.”

After saving the field, in the “Advanced” tab, you will need to enter the following code:

				
					$currentOperationId = Deep::registry('current_operation')->getId() ? Deep::registry('current_operation')->getId() : -1;
//Collection filter vars
$bind = [
    'src_model_id' => $currentOperationId,
    'src_model_alias' => 'deep_service/operation'
];
// URL params 
$additionalUrlParams = [
    'bind' => Deep::helper('deep_admin')->getBase64UrlString($bind),
];
// Merge with extra URL params
$element['url_params'] = array_merge($element['url_params'], $additionalUrlParams); 

				
			

With this code we are going to show in the grid only the movements related to the ticket.

After creating the field it will be necessary to add it to the form.
To add it, it will be necessary to press the pencil icon in the upper left corner.

In the floating window that will open we select the fieldset where we want to add the field (1) and from the list on the right we move the field by pressing the highlighted button (2).

After saving the template, the field will look like this:

To add a movement related to the ticket, simply click the “Add Movement” button and fill out the form that opens.

Once the movements have been added, the field will appear as follows:

To invoice the movements related to a ticket, you will need to fill out the invoice form by entering as follows:

The Model Alias will correspond to “DeepService – Operation” and the Model Id will correspond to the ID of the operation to be billed.

NOTE: For the movement to be shown in the grid, the movement item must be linked to a product in the catalog.

Operation Billing

This article will explain how to configure a button that opens the invoice form, linking it directly to the ticket.

As a first step you will need to create the button, this will open a floating window with the pre-filled invoice data.

In the interested formtemplate we click the pencil icon in the upper left side.

In the floating window that will open, right-click on “Buttons” (1) and click “New Button”.

After pressing the button, the new button will be created.

We proceed to open it (1) and replace the label “New Button” (2) with, for example, “Invoice”.

Next, we insert the following code inside the OnClick.

				
					$url = Deep::getUrl('*/sales_invoice/new', [
        'type' => 1,
        'only_content' => 1,
    ]);
$operation =  Deep::registry('current_model_instance');
$accountId = Deep::getModel('deep_company/company')->load($operation->getRequesterCompanyId())->getAccountId();
$urlParms = http_build_query([
        'invoice[model_id]' => $operation->getId(),
        'invoice[model_alias]' => 'deep_service/operation',
        'invoice[account_id]' => $accountId,
        'invoice[name]' => 'Invoice Operation #'.$operation->getId()
    ]);
$url = $url . "?" . $urlParms;
$jsFloating = <<<JS
    Deep.floatingWindow({
        url: '{$url}'
    });
JS;
return $jsFloating;

				
			

With this configuration, when the Invoice button is clicked, a floating window will be opened to create the already pre-filled invoice.

Integrations

Teams Integration

Through the Teams integration, it will be possible to use Microsoft Teams for the following activities with Deepser:

  • Open New Tickets
  • Modify basic information (Status, Assigned User, Priority)
  • Read/Add comments
  • Receive notifications
The key aspect of this integration is that it functions as an alternative notification channel. Moreover, it can also be used by those in customer service.
 
The opening and updating of tickets through this integration is designed exclusively for internal use and not for customers.
 

NOTES:

  • (internal) End users can only add comments to a ticket.
  • Other types of users can also modify Status, Assigned User, and Priority.
After the configuration, each user who has access to the Deepser app on Teams will be able to receive notifications about their respective tickets.

Enable API for a User

Team Integration is based on Deepser API, so the creation of a ticket from Microsoft Teams must be associated with an existing and well-configured admin user.

Therefore, you need to enable the Token for the user you want to authenticate.

To do that, you have to login into Deepser as a System Admin.
Go to the Configuration for the User you want to enable to token Authentication through API.
The menu in Deepser is System > Permissions > Users and then select the user you need to enable for token authentication.

PLEASE NOTE: If the “API Token” field isn’t visible, expose it by pressing the edit form button.

Then expose the field by using drag and drop.

You can use the three buttons to perform automatic actions on the Token: generate, delete or copy to clipboard.

Enable Teams Integration

In the Configuration menu of Deepser accessible from System > Configuration  > INTEGRATION – Configurations you can set Teams integration as enabled and save:

Once the integration is enabled, a new item will be available in the menu:

Deepser – Configurations

To proceed with the integration configuration, you will first need to create an ‘App Configuration’.

Then click on Integration > Microsoft > Teams > App Configuration, and then on the ‘+ Add App Configuration’ button:

The configuration screen for our app will open:

Specifically, if you create a new app configuration, you will be asked for the following information:

Field

Definition

Name

Through this field, you can set your own custom name for the integration.

Api User

Team Integration is based on Deepser API, so the creation of a ticket must be associated to an existing and well configured admin user. Follow the instructions in the “Enable API for a User” section to do it.

Status

Field that enables or disables Team Integration with the current app.

Default Operation Status

Determines the default status of a ticket when created through Teams.

Default Operation Type

Determines the default type of a ticket when created through Teams.

Microsoft Id Field

With this field we associate a Deepser user with a Microsoft Teams user. The Microsoft ID is the main field used to associate users.

In the case of a standard configuration with provisioning enabled, the field will always have the value ‘External User ID’.

NOTE: To have the Microsoft ID correctly populated in Deepser users (and therefore be able to use it), it will be necessary to set up user provisioning. Otherwise, it will be necessary to somehow manually input the Microsoft ID in Deepser users or use a custom automation.

Notify Assigned User

Indicates if the assigned user of the ticket should be notified via Teams.

Notify Assigned Group

Indicates if the assigned group of the ticket should be notified via Teams.

Check the “Channels” section of this article for more information.

Notify Requester User

Indicates if requester user of the ticket should be notified via Teams.


After compiling and saving the app, two green buttons will appear at the top right of the screen:

The first step involves downloading the app to be installed on Teams. By clicking on ‘Download App’, the zip package will be downloaded to be uploaded to your organization on Teams.

Teams Admin Center – Configurations

After downloading the zip package, it will be necessary to upload it as an app in the Microsoft Teams admin center.

So we access to: https://admin.teams.microsoft.com/

and navigate to the section: Teams apps -> Manage Apps.

Next, upload the zip file previously downloaded from Deepser by clicking on ‘Actions -> + Upload new app’:

Once the app is uploaded, we can then search for it among our apps to set the app’s availability (to everyone or to specific users or groups):

After doing this, we will need to wait for the app to propagate in Microsoft Teams.

NOTE: The time required for an app to propagate in Microsoft Teams can vary. Generally, propagation can take anywhere from a few minutes to an hour. However, in some cases, it may take longer depending on the complexity of the app and the organization’s settings.

We can now apply visibility policies:

  1. Go to “Teams apps” -> Setup policies.
  2. Click “Add” to add a new policy.

Under “Installed apps,” add “Deepser Bot.”

Under “Pinned apps,” add “Deepser Bot” and place it where it is most convenient.

Once the policy is created, switch tabs and go to “Group policy assignment”, click “Add” and add the group to which you want to apply the policy:

Adding the Deepser Bot App to the menu is important because users can receive notifications and create new tickets within it.

NOTE: The time required for a policy to propagate in Microsoft Teams can vary. Generally, propagation can take anywhere from a few minutes to an hour. However, in some cases, it may take longer depending on the complexity of the app and the organization’s settings.

Final Configurations – Teams and Deepser

Once the app has propagated, it will be necessary to access Teams and search for ‘Deepser Bot’ among your apps and add it to Teams and the navigation bar:

Now that can we access the app from the Menu, we can clicking on it and proceed the configuration. After accessing to Deepser Bot from Teams, we can execute “config” prompt:

And send it:

Then the following form will open:

As input for the prompt, it will be necessary to provide the configuration from Deepser. So we return to the configuration screen of our app in Deepser and click the ‘Copy Configuration’ button:

Once this step is complete, we return to the Deepser Bot in Teams, paste what we copied from Deepser, and save it:

Now all it’s configured.

NOTES:

  • The configuration procedure on the Teams App side is enabled for all users for the initial setup, but only for Deepser administrators for subsequent configurations.
  • Please note that on every change of the Deepser App Configurations (for example, in case of a status change, operation type change or other), it will be necessary to repeat this procedure to apply the configuration changes on the Teams side.

Ticket creation from Teams

Now that everything is configured, authorized users can proceed to create tickets by sending the ‘ticket’ prompt:

The app will respond with a message through which it will be possible to open a ticket clicking on “Create Ticket” button:

The user can set “Title”, “Urgency” and a little “Descritpion” for the ticket and clicking on “Submit” button the ticket will be created on Deepser.

When a change is made to the ticket or a comment is added in Deepser, users can receive a notification (based on the Deepser App Configuration). Below is an example:

Clicking on “Update” button, you can access on ticket edit from Teams:

On this form, if the user is a Deepser “End-User” can only add a comment as response.

If the user is admin, agent or key user can edit some basic fields like “Status”, “Assigned User”, “Priority” and Comments.

Furthermore can read the list of all related ticket comments.

Clicking on “View Ticket” button will open the ticket in Deepser End-User Portal.

Channels

In the Teams integration for Deepser, adding the app to a specific Teams channel will also create a “Channel” record within Deepser.

Channels created in this way will serve to convey notifications directly to a specific group:

The channel configuration can be done in the following ways:

  • During setup, if after configuring the app we add it to a Teams channel, the entity is created.
  • Through a command to be executed within the channel (upload channels).

Once the channel records have been created in Deepser, it is necessary to configure them adding related groups:

In the given example, the “Support Group” is linked to the “Support” channel in Teams. Consequently, any ticket assigned to the “Support Group” in Deepser will be notified through Teams in the corresponding “Support” channel (Only if no Assigned User is specified for the ticket).

NinjaOne Integration

Deepser introduces a dedicated module for seamless integration with NinjaOne. The integration, through the additional configuration of a flow, enables the following functionalities:

  • Download all Organizations listed in NinjaOne
  • Download all Locations listed in NinjaOne
  • Download all Devices listed in NinjaOne
  • Download the latest Activities created in NinjaOne
  • Receive new Activities created in NinjaOne in real-time
  • Create or Update an Organization
  • Create or Update a Location
  • Create or Update a Device

Below is a summary of the available actions on the flow side regarding the integration:

Enable NinjaOne Integration on Deepser

To enable the integration module, navigate to Deepser’s menu in System > Configurations > Integrations – Configurations, select and enable NinjaOne, then Save.

Once the integration is enabled in the menu, you will be able to view the new item.

Organization

An “organization” in NinjaOne represents a logical division within the platform, designed to group devices, users, and configurations associated with a specific client, department, or any organizational unit.

Within Deepser, in the Integration > NinjaOne > Organization section, you will find the organizations created in NinjaOne and synchronized via our integration.

Below are the main fields provided and synchronized in Deepser:

FIELD

DEFINITION

Organization Id

This refers to the unique identifier automatically assigned by NinjaOne to the organization.

Name

This is the descriptive name of the organization.

Description

In this field, you can provide a more detailed description of the organization.

User Data

This field is intended to host additional data related to the organization, such as contact information, specific notes, or other customized metadata

Node Approval Mode

This parameter defines the method by which devices (or “nodes”) are approved for inclusion within the organization.

Tags

Tags are labels or keywords that can be assigned to the organization to facilitate classification, search, and grouping.

Fields

This term generally refers to custom fields that can be associated with the organization. These fields allow for additional, tailored information to be stored and managed.

With specific configurations, it is possible to link Organizations with other similar entities in Deepser, such as “Account” or “Company.”

Location

A location in NinjaOne represents a logical or physical grouping used to organize devices and resources within a specific area of an organization.

In Deepser, under the Integration > NinjaOne > Location section, you can find the locations that were created in NinjaOne and synchronized through our integration.

Below are the main fields provided and synchronized in Deepser:

FIELD

DEFINITION

Location Id

This field represents the unique identifier of the location within the system.

Organization

It indicates the organization to which the location belongs.

Name

This is the descriptive name of the location.

Address

It collects the physical address of the location (such as street, city, postal code, country, etc.).

Description

In this field, you can include additional details and descriptive notes about the location.

User Data

This field is designed to host additional and customized data.

Tags

Tags are labels or keywords used to categorize the location.

Fields

This term refers to the custom fields associated with the location, allowing for tailored information specific to the location to be stored and managed.

With specific configurations, it is possible to link Locations with other similar entities in Deepser, such as “CI” (Configuration Items) of the “Location” class.

Device

A device in NinjaOne refers to any endpoint (physical or virtual) managed and monitored by the platform.

In Deepser, under the Integration > NinjaOne > Device section, you will find the devices created in NinjaOne and synchronized via our integration.

Below are the main fields provided and synchronized in Deepser:

FIELD

DEFINITION

Device Id

Unique identifier assigned to each device within the system.

Parent Device

This field indicates the ID of the “parent” device to which the current device belongs.

Organization

Indicates the organization (logical division or client) the device is associated with.

Address

Collects the physical address of the location (e.g., street, city, postal code, country, etc.).

Location

Specifies the site or location (physical or logical) where the device is located.

Device Type

Identifies the hardware type of the device.

Node Class

Indicates a general classification of the device at the “node” level.

Node Role

Specifies the operational role the device plays within the infrastructure.

Role Policy

Represents the set of rules associated with the device’s role.

Policy

Represents the series of configurations, rules, or automations applied to the device.

Approval Status

Indicates the approval status of the device within the system.

Offline

Displays the device’s connectivity status, such as whether the device is currently offline.

Display Name

The name displayed in the NinjaOne user interface to identify the device.

System Name

Usually represents the operating system name or internal asset name as recorded by the system.

DNS Name

The domain name associated with the device, useful for network resolutions and DNS-level identification.

Netbios Name

The NetBIOS name (typical in Windows environments) used to identify the device on the local network.

Created

The date and time the device was registered.

Last Contact

Indicates the last time the device communicated with the NinjaOne server.

Last Update

The date and time of the last update to the device’s data or configuration.

User Data

A field designed to host additional or customized data associated with the device.

Tags

Tags or keywords assigned to the device.

Fields

Reference to custom fields that can be associated with the device to extend the basic information.

Maintenance Status

Indicates whether the device is currently under maintenance or scheduled for planned interventions.

Maintenance Start

The start date and time of the scheduled maintenance window for the device.

Maintenance End

The end date and time of the maintenance window, after which the device returns to a normal operational state.

IP Addresses

List of IP addresses assigned to the device.

MAC Addresses

List of MAC addresses associated with the device’s network interfaces.

Public IP

The public IP address associated with the device.

Notes

A field that contains annotations or comments related to the device.

Disks

Information related to the device’s physical or virtual disks, including details like capacity, status, and configuration.

Operating Systems

Indicates the operating system installed on the device.

With specific configurations, it is possible to link Locations with other similar entities in Deepser, such as “CI” (Configuration Items) of the “Device” class.

Activity

An activity in NinjaOne represents an event logged in the system, such as the execution of a script, software update, remote action, status change, or error report.

Within Deepser, under the Integration > NinjaOne > Activity section, you can find activities created in NinjaOne and synchronized through our integration.

Here are the main fields provided and synchronized in Deepser:

FIELD

DEFINITION

Activity Id

Unique identifier of the activity in the system. 

Device

The device on which the activity was performed. 

Activity Time

Date and time when the activity occurred. 

Severity

Severity of the activity, indicating the importance or urgency of the event. 

Priority

Priority assigned to the activity, useful for determining the order of management. 

Series Uid

Identifier of the series of related activities, useful for tracking operations composed of multiple steps. 

Activity Type

Type of activity, such as “Script Execution,” “Software Installation,” or “Remote Session.” 

Status Code

Numerical code representing the activity’s state, such as completed or failed. 

Status

Textual description of the activity’s state, e.g., “Success” or “Failed.” 

Activity Result

Result of the activity, providing details on the outcome. 

Source Config Uid

Identifier of the source configuration that generated the activity, such as a policy or a trigger. 

Source Name

Name of the source that originated the activity. 

Subject

Object or title of the activity, useful for quick identification. 

User

User who executed or initiated the activity. 

Message

Message associated with the activity, providing additional details or descriptions. 

Type

Category of the activity, such as “Automated” or “Manual.” 

Data

Additional data related to the activity, which may include specific parameters or detailed results. 

With specific configurations, it is possible to link Locations with other similar entities in Deepser, such as “Operations”.

Deepser – Connection and Client OAuth Configurations

To proceed with the integration setup, you need to create a new connection and an OAuth client.

Then, navigate to System > Integration > NinjaOne > Connection and click the “Add Connection” button. Let me know if you’d like further guidance on this!

 

The Connection Configuration screen will open:

The following information is required:

FIELD

DEFINITION

Name

Set a custom name for the connection

OAuth Client

Select the OAuth client to be used for the connection with NinjaOne. By clicking the “+” icon below, a window will open to create a new OAuth client. The fields related to this form are described in the next table.

Status

To create a new OAuth Client, the following information will be required

 

For the creation of a new OAuth Client, the following information will be required:

FIELD

DEFINITION

Redirect Uri

OAuth Client URI generated by Deepser required by the NinjaOne app. The URI will be generated and displayed after the first creation of the file.

Name

Set a custom name for the OAuth Client.

Status

Field to enable or disable the OAuth client.

Provider

Select “NinjaOne.”

Domain

Select the domain of your “NinjaOne” instance. For installations in Europe, the standard domain is EMEA.

Client ID

Enter the Client ID generated by the NinjaOne app.

Client Secret

Enter the Client Secret generated by the NinjaOne app.

 

The creation of the app in NinjaOne is described in the following paragraph.

NinjaOne – API Configuration

Su NinjaOne, navigare fino a Administration / Apps / API:

From the API screen, click “Add” and the following screen will open:

Select “Web (PHP, Java, .Net Core, etc.)” option.

Fill the form with the following information:

  • The Redirect URI of Deepser’s OAuth Client.
  • The Scopes needed.
  • Authorization Code and Refresh Token as Allowed Grant Types.

Below is an example configuration:

By clicking the Save button in the upper right corner, NinjaOne will generate the Client Secret. 

Copy this value and enter it in the Client Secret field of Deepser’s OAuth Client.

 

NOTE: Make sure to copy and save this value, as the Client Secret will no longer be available once you leave this page!

Click the Close button, and you will return to the Administration / Apps / API screen. 

From there, copy the Client ID generated by NinjaOne and paste it into the Client ID field of Deepser’s OAuth Client.

Below is an example configuration of a Deepser OAuth Client:

Click the Validate button in the Deepser OAuth Client form. 

In the screen that opens, click Authorize:

If the authentication returns the message “Client was successfully authorized”, the NinjaOne Client is correctly configured and ready to be used within a Connection.

Deepser – Download Data from NinjaOne

To retrieve all objects in NinjaOne and create them in Deepser, we will use a dedicated flow that handles the creation and/or updating of Organization, Location, Device, and Activity

NOTA: Generally, these types of flows are used only in the initial phase to establish a working foundation, but there is nothing preventing you from using this method to retrieve information from NinjaOne.

Let’s proceed with creating a new Flow:

  1. First, configure a trigger by setting the automatic execution of the flow once per day:

  2. By clicking the “+” icon, proceed to configure a node to download all organizations via: Action >      Integration > NinjaOne > Download Multiple > Organizations:

Once the action has been added, select the previously configured connection to NinjaOne:

 3. Once the Organizations have been retrieved, we can proceed to iterate through them. Add a   new node by clicking the “+” button, then select Logic > Foreach:

Select the collection of organizations created earlier (from the right-hand menu):

Finally, based on each Organization obtained through Foreach, retrieve the Locations and Devices associated with each Organization.

 4. Additionally, it is possible to retrieve part of the Activities as a historical record. To do this, you   need to iterate through the Devices:

And then retrieve the latest 200 Activities associated with each Device.

The complete flow will be as follows:

The flow will handle the creation and updating of objects retrieved from NinjaOne in Deepser, including Organizations, Locations, Devices, and Activities.

The example flow will automatically execute every day at 8:00 AM (this parameter can be modified in the Trigger settings).

You can manually run the flow by clicking the Run Now button in the Trigger section of the flow.

IMPORTANT NOTE 1: For the nodes in rows 1, 3, 4, and 6, ensure that the selected Connection is the one configured earlier.

IMPORTANT NOTE 2: Node 6 is used to retrieve the latest 200 Activities (alerts) generated for each Device. It is recommended to keep this node only for the first execution of the flow. Future Activities created in NinjaOne will also be created in Deepser through an additional flow. Alternatively, you may choose to remove this node (along with Node 5).

IMPORTANT NOTE 3: Enable the flow once it has been imported.

CRM

 

Deepser’s CRM (Customer Relationship Management) module is used to manage, control and maintain a Customer, Contacts and Customer Base. It is also possible to Manage Sales Opportunities, tracking their possible profits, probabilities and related Tasks

Articles

  • Deep CRM
  • Creating an account in the CRM
  • Creating a contact in the CRM
  • Creating an opportunity in the CRM
  • Contact Types in CRM
  • Opportunity Types in CRM
  • CRM Lists
  • Sync Contacts and Accounts
  • Address Functioning
  • Sales
  • Mailchimp Integration

Deep CRM

Deepser’s CRM (Customer Relationship Management) module is used to manage, control and maintain a Customer, Contacts and Companies Park. It is also possible to Manage Sales Opportunities, tracking their possible profits, probabilities and related Tasks.

The CRM consists of three categories:

  • Account: Allows to Maintain Data Relating to Customer Companies and Related Divisions

  • Contacts: Tracks Contacts and Leads

  • Opportunities: Organize business opportunities and describe the next steps to take

Creating an account in the CRM

The following guide addresses the issue of creating an Account in the CRM, explaining the meaning of the standard input form fields.

1 – Open CRM – Account, Via CRM -> Account

2 – The following fields will be displayed in the Insert Form:

The meaning of the fields is as follows:

CampDescription
NameThe Company Account Name
TypeIndicates the type of Account
Parent AccountAllows you to Establish a hierarchy between different accounts. He then manages Divisions and Corporate Headquarters. For example, an ACME Account may be parent of ACME Italy and ACME France.
StateEnable or Disable L Account
Linked CompanyField that maintains a reference to a Company present in Deepser Companies. (See the section Buttons)
Owner UserAllows you to specify the Account Administrator.
WebsiteMy Account website
PhoneYour Account Phone Number
FaxFax of Account
IndustryArea of Account Reference
EmployeesNumber of Employees
Satisfaction RatingCustomer Account Satisfaction Level
LogoAccount Logo Image
NotesAdditional Notes
TaskTask Related to Account

Creating a contact in the CRM

The following guide addresses the issue of creating a Contact in the CRM, explaining the meaning of the standard input form fields.

1 – Open the CRM and Select the type of contact concerned, via CRM -> Contacts

1a – The insertion form consists of two sections:

  • Contact: Contains contact details
  • Contacts: Contains contact details such as phone number, email, etc.

2 – The following fields will be displayed in the Contact Entry Form:

The meaning of the fields is as follows:

CampDescription
NameName of the Contact
SurnameSurname of the Contact
SalutationAllows you to Pin the greeting with which Refer to the contact (e.g. Lady or Miss)
StateEnable or Disable L Account
DepartmentThe Department to which the Contact belongs
QualificationThe status of the Contact
ManagerAllows Specifying a Contact Manager
SourceIndicates the source from which the Lead was generated
RatingCustomer Account Satisfaction Level
Associate userAllows Associating Contact to a System User on Deepser
TaskTask Related to Contact

The Contacts tab contains the followingfields:

The meaning of the fields is as follows:

CampDescription
EmailEmail of the Contact
TelephoneNumber of Fixed Telephony
Mobile phoneNumber of Mobile Telephony
FaxFax of the Contact
AddressAddress of the Contact
CityCity of Contact
ProvinceProvince of Contact
CAPCap of the Contact
StateState

Creating an opportunity in the CRM

The following guide addresses the issue of creating an Opportunity in the CRM, explaining the meaning of the standard input form fields.

1 – Open the CRM – Account, Via CRM -> Opportunity

2 – The following fields will be displayed in the Insert Form:

The meaning of the fields is as follows:

SectionFieldsDescription
Expediency                TitleThe Company Account Name
 State Indicates the type of Account
 Typology BusinessIndicates the type of Opportunity
 AccountIndicate the reference account
 ContactingIndicates the reference contact
 DescriptionAllows you to enter a description of the opportunity
 User OwnerAllows to indicate a user owner of the Opportunity
 SourceIndicates the source that generated the following opportunity
 Loss ReasonIndicates the reason that led to the loss/renunciation of opportunity
Amounts    AmountSpecify the sum of money that could generate the opportunity
 Budget Confirmed Indicates the confirmation status of the Sum
 ProbabilityIndicates the probability of obtaining this sum
Step  Next Step TitleIndicates the title of the next step needed to get the opportunity.
 Next Step DescriptionIndicates the description of the next step needed to get the opportunity.

Contact Types in CRM

The following guide deals with the creation of a customized Contact Type, in addition to those already present in the system, Contact and Lead.

1 – Open the system configuration for Contact Types, via System-> CRM Configuration -> Contact Types

2 – Click Add Type Contact

3 – Below is the standard Insert form

The meaning of the fields is as follows:

FieldDescription
NameThe name of the type of Contact
ClassIndicates the class of the Contact type
DescriptionIndicates the description of the type of Contact
IconAllows to load an icon for the type of Contact
LocationIndicates the position of the typology compared to other existing typologies
Groups EnabledIndicates the groups enabled to create Contacts of this type
StateIndicates status(Enabled/Disabled)

4 – When the fields have been completed, click Save.The new type of Contact will be present in the CRM

Opportunity Types in CRM

The following guide deals with the creation of a customized Type of Opportunity, in addition to those already present in the system.

1 – Open the system configuration for the Types of Opportunities, via System-> CRM Configuration -> Types of Opportunities

2 – Click Add Typology Opportunities

3 – Below is the standard Insert form

The meaning of the fields is as follows:

CampDescription
NameThe name of the typology of Opportunity
LocationIndicates the position of the typology compared to other existing typologies
DescriptionIndicates the description of the type of Opportunity
IconAllows to load an icon for the type of Opportunity
Groups EnabledIndicates the groups enabled to create Opportunities of this type
StateIndicates status(Enabled/Disabled)

4 – When the fields have been completed, click Save.The new type of Opportunity will be present in the CRM

CRM Lists

In the various models present in the CRM are included several fields of list type, an example is the Source of the Contacts of the CRM.

All these lists are present in the system configuration, and therefore are freely customizable.
Please Note: The article superficially deals with the issue of list management. To find out more, see the appropriate section of the Academy.

Here are the lists used for the various models:

  • Account
    • Industry(crm_account_industry): Reference Account Sector
    • Type(crm_account_type): The type of Account
    • Satisfaction(crm_account_satisfaction): The Customer Account Satisfaction Level
  • Contact
    • Rating(crm_contact_rating): The evaluation of the Contact
    • Source(crm_contact_source): The source of the contact, so how it was obtained
  • Opportunity
    • Business Type(crm_opportunity_business_type): The type of Opportunity
    • Source(crm_opportunity_source): The Source of Opportunity
    • Loss Reason(crm_opportunity_loss): Indicates the motivation that led to the eventual loss of opportunity
    • Status(crm_opportunity_business_status): Indicate The custom status of Opportunity_status

Lists are editable in System->Configuration->Tools->Lists

Sync Contacts and Accounts

In the CRM there are the forms Contacts and Accounts, these are not synchronized automatically. This is possible through the synchronization functionalities.

In the CRM – Account module, a Sync Company button is included:  Pressing this button will automatically sync the account with a Company. This synchronization does not automatically keep non-standard fields synchronized.

In the CRM – Contact module, the following buttons are available:

  • For Leads, Convert to Contact to convert to Contact
  • For Leads, Sync User to convert to Deepser User, and keep it in sync

Address Functioning

In Deepser, Addresses can be understood as actual places, companies, or accounts.

The use of Addresses, for example, allows us to manage a company’s Multi-Locations.

  1. In this case, let’s take the Addresses of an account as an example.
    To access this area, click on Crm->Account.

2. Select the account to add its addresses.

3. Select the Address option in the grid on the left.

4. After that, the following screen will appear.

Here you will find the address data related to the main account.

 

Below is a brief explanation of the fields displayed in the form.

Field

Description

Billing Address

Billing Address

Billing City

Billing City

Billing Zip Code

Postal code of the billing city

Billing State

Billing Country

Billing Country

Billing Country

Shipping Address

Shipping Address

Shipping City

Shipping City

Shipping Zip Code

Postal code of the shipping city

Shipping State

Shipping Country

Shipping Country

Shipping Country

 

5. To save your changes, click Apply or Save to save them.

Below is a detailed description of the available buttons:

1 – To return to the previous page without saving.

2 – To reset the information to the last save.

3 – To delete the entered record.

4 – To save and return to the main grid.

5 – To save and stay on the current page.

6 – To synchronize Account -> Company (Present only if the Sync function is enabled).

 

 

6. At the bottom of the Form there is an Address Grid Field (custom fields), in this case ‘Sales Addresses‘, in which you can enter different addresses of companies connected to the main one.

For example, a common use of Addresses is the management of multi-locations, detachments, branches, etc.

7. To add a new address, click the blue Add Address button in the top right corner.

8. The following screen will appear.

Below is a brief description of the fields in the form.

Field

Description

Company Name

Name of the venue

Company Code

Company Code

Address

Address

Zip Code

Postal code

Country

State

Is Default

If there are multiple adresses associated with the company, only one can be designated as the default.

It will be suggested as the default address for address fields in CRM Sales modules.

Status

Set to ‘Enabled‘ to enable it

9. To save, press Apply in the top right corner.

The new address entered, after saving, will be added to the grid below.

Sales

Sales module is located inside CRM module and is used to keep record of sales department. This module has different entities such as quotes, orders, invoices and shipments. 

Quotes

Quotes is an entity inside the sales (1) module and is used to create different quotes based on the products that the client requires.

On the right side we have:

  • the button to create a new quote (2).
  • the grid with all present quotes (3).

Add quote

Add quote is used to create a new quote and has a default form that can be modified to the user’s needs. On the left side (2) we have a menu for different sections of the form.

On the right side we have the form data that will be populated with quote data.

Some of the visible fields are:

  1. Main data:
    • Account -> account related to this quote.
    • Name -> name of the quote.
    • Status -> status of the quote (accepted, draft, rejected à other values can be added in this list)
    • Currency -> currency on which the products price will be calculated.
    • Price list -> shows the list of prices that is associated with this quote.
  2. Payment:
    • Payment condition
    • Billing address
  3. Invoice:
    • Invoice is a grid that contains the invoices created from this quote. You can add, modify, and delete invoices directly from here.

After filling the data and saving, we will see these new fields on the Quote form:

 

  1. We have the button on the right top to create an order based on this quote and with the given products. This will create a record on the Order entity of the Sales module.
  2. It is the grid that displays the products added to this quote. You can add more or delete the selected ones. The products are retrieved from the Catalog

Order

Order is another entity inside Sales (1) and is used to:

  • Manage orders that are created from the quotes entity
  • Create a new order without a quote relation. You can do it by clicking the Create order button and selecting the order type you want it to be (2). Below the button, there’s the grid that displays all available orders.

Add order

An order can be created from quote entity or by clicking create new order. If we create it from the quote entity, the quote field will be populated with a link to the quote which this order is created from.

Some of the visible fields are:

  1. Main data
    • Account -> account related to this order.
    • Name -> name of the order.
    • Status -> status of the order (accepted, draft, rejected)
    • Currency -> currency on which the products price will be calculated.
    • Price list -> shows the list of prices that is associated with this order.
    • Quote -> if the order is created from quote this field will be populated with a link that will redirect to respective quote.
  2. Payment
    • Payment condition
    • Billing address
  3. Shipment
    • Shipment grid -> shows all shipment related to this order. You can add, modify, delete shipments from this grid.
  4. Invoice
    • Invoice is a grid that contains the invoices created from this quote. You can add, modify, and delete invoices from here.

After filling the data and saving we will see these new fields on the Order form.

 

  1. On the right top there’s the button to create a shipment for this order.
  2. On the right top there’s the button to create an invoice for this order.
  3. It’s the grid that displays the products added to this order. You can add more or delete the selected ones. The products are retrieved from the Catalog module.
  4. It’s the quote that is related with this order.

 

Invoice

Invoice is another entity inside Sales (1) and is used to manage invoices that are created from the Quote entity or from the Order entity. You can create a new invoice without a quote or order relation. You can do it by clicking the Create invoice button and selecting the invoice type you want it to be (2). Below the button is the grid that displays all available invoices. (3)

Add Invoice

An invoice can be created from Quote entity or Order entity. You can create it also by clicking the Add Invoice button on the top right side.

Some of the visible fields are:

     1. Main data

    • Account -> account related to this invoice.
    • Name -> name of the invoice.
    • Status -> status of the invoice (enabled, disabled)
    • Model alias -> is the model from which the invoice is created from.
    • Model id -> is the id of the entity that created the invoice.
    • Currency -> currency on which the products price will be calculated.
    • Price list -> shows the list of prices that is associated with this order.

     2. Payment

  • Payment condition
  •  Billing address

     3. Activities and Movements

    • Invoice Related Models is a grid relation that contains the activities related to this invoice. You can add, modify, and delete activities from here.
    • Invoice Related Movements is a grid relation that contains all the warehouse movements connected to this invoice.

After filling the data and saving we will see this new fields on the Invoice form:

Invoice Items is the grid that displays the products added to this invoice. You can add more or delete the selected ones. The products are retrieved from the Catalog module.

 

Shipment

Shipment is another entity inside Sales (1) and is used to manage Shipments that are created from the order entity. When you click on the Shipment section from the left menu, the grid with all the shipments that are generated from the orders is shown.

Edit Shipment

Some of the visible fields are:

1. Shipment

 Account -> account related to this shipment.

 Name -> name of the shipment.

 Status -> status of the order (delivered, received, canceled. Other values can be added)

 Shipping Date -> the Date of shipment.

2. Addresses

Billing Address -> you can select the billing address of the shipment.

  •  Items is the grid that displays the products added to this invoice. You can add more or delete the selected ones. The products are retrieved from the Catalog
  •  Order is a link that opens the Order that is related with this shipment.

Mailchimp Integration

The mentioned integration allows you to one-way synchronize contacts between Deepser and Mailchimp.

As a result, it allows you to automate marketing processes and improve customer management.

The operation of this integration therefore allows you to intervene on Mailchimp audiences, allowing the addition, modification and deletion of contacts.

Mailchimp account configuration

To proceed with the configuration, it will be necessary to access to the “Mailchimp” module from the main menu:

From here, you’ll be able to proceed to set up one or more Mailchimp accounts that you want to interact with.

To do this, it will be necessary to click on “+ Add Account” at the top right of the page and we will find ourselves in front of the following screen:

Below are the details of the fields:

Field

Definition

Server Prefix

The server prefix is the starting part of the endpoint URL. For example, to find your server prefix, you must log into your Mailchimp account and look at the URL in your browser. You’ll see something like https://us19.admin.mailchimp.com/; the us19 part is the server prefix.

 

So, you need to set that value into “Server Prefix” field in Deepser.

Token

API keys grant full access to your Mailchimp account.

To generate an API key, follow these steps.

  1. Click your profile icon and choose Profile.
  2. Click the Extras drop-down then choose API keys.
  3. In the Your API Keys section, click Create A Key.
  4. Name your key. Be descriptive, so you know what app uses that key. Keep in mind that you’ll see only this name and the first 4 key digits on your list of API keys.
  5. Click Generate Key.
  6. Once we generate your key, click Copy Key to Clipboard. Save your key someplace secure–you won’t be able to see or copy it again. If you lose this key, you’ll need to generate a new key and update any integration that uses it.
  7. Click Done.

 

So, after copying the token, you can paste it into “Token” field in Deepser.

Cron Expression

To keep your data between Deepser and Mailchimp up to date, you can schedule syncing at predefined intervals via this field.

Mailchimp Username

There is no need to enhance this field. It will be automatically valued when the record is saved if correctly configured.

Email

There is no need to enhance this field. It will be automatically valued when the record is saved if correctly configured.

Status

A field that allows you to enable or disable the mailchimp account in use on Deepser.


Once the system has been correctly configured, using the “Check” button it will be possible to check the correctness of the data entered. The message that determines a correct configuration will be as follows:

After saving, the “Audiences” grid will be displayed which will serve to contain the information synchronized between the 2 systems.

Note: Only once the synchronization process is complete will the information in it be available.

To perform the synchronization, it will be possible to proceed manually by clicking on the “Sync” button. In this case, if you have a lot of information on your account that needs to be synced, it may take some time for it to fully sync.

Alternatively, you can wait for the synchronization schedule to run automatically based on the configuration of the “Cron Expression” field.

The following information is available within an Audience record:

Field

Definition

Name

In this field, you will find the name of the audience synced with Deepser.

Contacts

Within this grid, only contacts that have been synced from Deepser to Mailchimp will be available.

This means that you won’t have any contacts that were previously in Mailchimp.

 

NOTE: Within this grid you will not see the classic Deepser contacts present in the CRM section, but they are contacts linked to the Mailchimp form and can only be viewed through this grid.

Tags

Within this grid, you’ ll see all the Tags in Mailchimp that are synced to Deepser, for the account you set up.

Mailchimp flow configurations

To proceed with the integration with mailchimp on Deepser, you will need to use the flows module for creating your own automations for mailchimp contacts.

In fact, searching among the actions available in the flows, we can find the following:

Check Mailchimp Contact

Through this action, it will be possible to verify the existence of a particular Mailchimp contact present within an account previously configured on Deepser.

In fact, the action in question will return a Boolean value (true/false) that can eventually be used in a conditional block (if, if-else or others).

The following is the information required in this type of block:

Field

Definition

Mailchimp Account

Through this field you can select one of the accounts configured through the “Mailchimp” module.

Mailchimp Audience

Through this field you can select an audience linked to the selected account.

Model

Through this field it will be possible to associate a model through which to carry out the verification. For example, a record of type “Mailchimp Contacts” or a record of type “CRM Contacts.”

Email Field

The following field will be prompted, only if the selected template is different from “Mailchimp Contacts”.

Create or Update Contact

Through this action, you will be able to create or edit a particular Mailchimp contact within an account previously configured on Deepser.

The action in question will allow you to map the fields of the “Mailchimp Contacts” module and another Deepser module (typically a CRM Contact).

The following is the information required in this type of block:

Field

Definition

Mailchimp Account

Through this field you can select one of the accounts configured through the “Mailchimp” module.

Mailchimp Audience

Through this field you can select an audience linked to the selected account.

Model

Through this field it will be possible to associate a model through which to carry out the verification. For example, a record of type “Mailchimp Contacts” or a record of type “CRM Contacts.”

Status

Through this field you can update the status of the contact on mailchimp, i.e. whether he is subscribed to an audience or not.

Field Mapping

Using this multivalue field, you can map the fields between the “Mailchimp Contacts” module and another Deepser module (e.g. “CRM Contacts”).

Tags

Through the field in question, you can add one or more tags to the contact, among those defined and synchronized with Mailchimp.

Tag Change Type

Through this field, you can intervene in updating the tags in the following way:

 

– Override all Tags: To delete the old tags related to the contact and therefore add only those indicated through the “Tags” field.

 

– Add Tag: To add the tags indicated through the “Tags” field without deleting any tags related to the contact.

 

– Remove Tag: To remove tags specified via the “Tags” field from the contact.

NOTE: When a Mailchimp contact is created/edited, the originating pattern used will be tied to the record via a 1:1 relationship. For example, if you create a Mailchimp contact from a CRM Contacts record, the two records CRM Contacts and Mailchimp Contacts will be linked to each other.

Delete Contact

Through this action, it will be possible to delete a particular Mailchimp contact present within an account previously configured on Deepser.

The following is the information required in this type of block:

Field

Definition

Mailchimp Account

Through this field you can select one of the accounts configured through the “Mailchimp” module.

Mailchimp Audience

Through this field it is possible to select the target audience linked to the selected account.

Model

Through this field it will be possible to associate the mailchimp contact template to be deleted or its linked template (e.g. its CRM Contacts used for creation/update).

 

In either case, the deletion will only be done on the Mailchimp contact and never on the linked template.

Delete Type

Through this field, you can intervene to indicate the method of cancellation of the Contact, which can be:

 

– Archive Contact: Which allows you to archive the contact on Mailchimp

 

– Permanent Delete Contact: Which performs a permanent delete on Mailchimp.

 

LDAP Configuration

Deepser natively supports integration with the LDAP protocol.

LDAP is a protocol for centralized resource management.

Deepser’s LDAP integration allows you to easily import users and or groups containing users that you will need to be enrolled to be managed/enabled in Deepser from an existing LDAP installation.

Note that Deepser synchronizes resources with LDAP in read-only mode and can independently manage the update of states or generally modified parameters on the LDAP Resources placed in the LDAP controller, this translates into the fact that if a user is moved to group or disabled or  in general changes are made to the user on the LDAP controller the same changes,  in a standard case, will be replicated on Deepser.

CONFIGURING LDAP INTEGRATION

To configure an LDAP integration on Deepser you will need to go to the System -> Permission  -> LDAP Integration menu

In the screen that will open, you will be able to view the LDAP integrations already configured and configure new ones.

To configure a new integration, you will need to click on the Add LDAP button.

After that the following screen will open:

Below are the fields present and their meaning:

FieldDescription
Show In LoginThis field indicates whether this LDAP integration will be visible on the login page
Is DefaultIndicates whether this LDAP integration will be the one selected by default in the list on the login page
NameLDAP Integration Name
Domain ControllerThe address at which to find the domain controller.
Cron ExpressionCron expression that indicates how often the integration will be performed.
StatusIndicates whether this integration is active or not, if it is not active the synchronization will not be performed.
Base DN  Domain base name, this field indicates the point below which Deepser will have visibility in the domain forest. 
Time-outIndicates the maximum time within which if a request is not answered, the request must be considered expired.
Use SSLIndicates whether the domain controller uses S.S.L. encryption
Use TLSIndicates whether the domain controller uses T.L.S. encryption
Follow ReferralsThis field indicates whether to follow the referral links generated by the LDAP controller. Referral links are links that indicate that the server you are    querying does not directly own the requested resource, but has a reference to the server or domain that owns that resource.
Admin UsernameUsername of the user that Deepser will use to read domain’s users.
Admin PasswordPassword of the user account that Deepser will use to read access the Domain Controller.

In the Users Configuration section, you will define how users will be synchronized in Deepser.

Below are the fields in this section and their meaning:

FieldDescription
User Name AttributeIndicates which field of the response obtained from the domain controller will contain the user’s name
User RDN AttributeThis field is the field that indicates the path relative to another entity (parent) of the resource in the Domains Forest .  ES:  distinguishedname.
User Fields  This field is used to map the relation between domain user’s fields and user’s fields in Deepser
User Object FilterThis field is used to specify an LDAP query, this will serve as a filter to retrieve only users who match the search criteria.
Account PrefixAccount prefix e.g.: “EXAMPLE\<username>”. In this case “EXAMPLE\” is the account prefix.
Account SuffixAccount suffix ex: “<username>@example.local”. in this case “@example.local” is the account suffix.
Disable UsersThis field indicates whether users created on AD as disabled should be imported as disabled or not.
Custom CodeCustom code to indicate how user field values imported from integration are assigned.

In the Groups Configuration section, you will define how groups will be synchronized in Deepser.

Below is a list of the fields present and their meaning:

FieldDescription
Group EnableThis field is used to enable  the import of groups into Deepser from the forest.
Group Base DN  Indicates which is the name of the base domain in which the groups reside (e.i.: cn=exemple,  dn=com)
Group Name AttributeIndicates which field in the object returned by the request to the domain controller will contain the name of the group.
Group Members Attribute  Indicates which field in the object returned by the request to the domain controller will contain the list of users who belong to the group
Group Object FilterThis field is used to specify an LDAP query, this will serve as a filter to retrieve only the groups that match the search criteria.
Group Fields  This field is used to bind domain group fields to group fields in Deepser

Once the fields have been configured, you will need to click on the “Save” or “Apply” button.

At this point, by clicking on the “Check LDAP” button, you can check if the integration works correctly.

If the integration works correctly, a green banner will be displayed in the upper right corner of the page.

In case of error, you will see a red banner in the upper right corner of the page.

Deepser API

 

This is an advaced – developer focused – course that aims to teach everything about Deepser’s Rest APIs.

Articles

  • API Notions
  • API Endpoint and URL
  • API Verbs and Format
  • API Authentication
  • API Main Methods
  • Retrieve
  • Multiple Retrieve
  • Create
  • Update
  • Delete
  • API Entities
  • API Company
  • User API
  • Group API
  • Service Operation API
  • Service Type API
  • Activity API
  • CMDB CI API

API Notions

Deepser was designed to meet all IT department needs.
The Deepser REST API was designed to meet specific needs for the customization and integration of the software, in particular:

  • Retrieve, store and process data in the best way for your organization
  • Interface and integrate Deepser with third party applications

API REST is natively supported by any version of Deepser.
Before you start reading the guide it is important to know some key concepts, described in this lesson.

API Endpoint and URL

You access the resource by sending an HTTP request to the Deepser API server. The server replies with a response that contains either the data you requested, or the status indicator, or even both.
Common characteristics of Deepser REST API resources are as follows: (deepserhost is your domain)

  • To access the API you have to call the endpoint at: 
http[s]://deepserhost/api/rest/
  • You request a particular resource by adding a particular path to the base URL that specifies the resource.
  • The server replies with a response that contains either the data you requested, or the status indicator, or even both.

REQUEST STRUCTURE

All URLs in REST API have the following base URL.

http[s]://deepserhost/api/rest/

Example:
Supposing you want to retrieve the list of Companies from Deepser.
To do this, you need to use the GET HTTP method.

The GET request to retrieve the list of Companies will look as follows:

http[s]://deepserhost/api/rest/companies

where:

  • http[s]://deepserhost/api/rest is the endpoint
  • /companies is the action URL

UNDERSTANDING ROUTES

Typically, Deepser has 2 main routes for each entity’s action URL.
The first one, we have just seen, is used to retrieve the entity collection, so it is generally the name of the entity in a plural form. For the entity Company it is:

http[s]://deepserhost/api/rest/companies

It must be called using an HTTP GET request and can be followed by filters or parameters (described in the next chapters) to provide the desired selection of the records.
For example, if we want to retrieve only the first Company with name starting with ‘ACME’, we should use this HTTP request to the REST API:

http[s]://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&limit=1

We will explain in the next chapters all the filters and parameters.
To analyze this simple request, we have defined (after the endpoint and the route):

  • filter: an array containing in each element the structure of the filter
  • [attribute]: the element of each filter with the attribute to filter
  • [like]: the element of each filter with the selection type (in our case we want a SQL like)
  • limit: a parameter to limit the response results to just one element

If we want to retrieve a single element (eg: for which we already know the ID) we don’t use the routes to access a collection, but we use the route to get the single entity.
This is typically the name of the entity, followed by the ID of the entity.
In our example we get the company with ID = 4

http[s]://deepserhost/api/rest/company/4

It will retrieve all fields of the company with ID = 4.

API Verbs and Format

HTTP verbs are used to manage the state of resources.
In Deepser REST API there are four verbs used to manage resources: GET, POST, PUT, and DELETE.
You can:

  • Create new entity data using HTTP POST
  • Retrive the contents of the data using HTTP GET
  • Update the data using PUT
  • Delete the data using HTTP DELETE

API AUTHORIZATION

Deepser API uses those methods to get, create, update or delete entities.
Based on the entity, on the role and the permissions of the logged-in user, there are different actions allowed.
The details will be explained in the next chapters, but you must remember the actions implemented by the API are:

  • Create: to create a single resource (HTTP POST)
  • Retrieve: to get a single resource (HTTP GET)
  • Update: to update a single resource (HTTP PUT)
  • Delete: to delete a single resource (HTTP DELETE)
  • Multiple Retrieve: to get multiple resources (HTTP GET)
  • Multiple Create: to create multiple resources (HTTP POST)
  • Multiple Update: : to update multiple resources (HTTP PUT)

Multiple Delete is not allowed for Security Reasons.

API FORMAT

The REST API response is a JSON object, depending on the resource requested.
A brief example (we will describe in the next chapters in details) is the following:

				
					{
   "totalRecords":2,
   "items":[
      {
         "entity_id":"1",
         "parent_id":"0",
         "sort_order":null,
         "name":"ACME International",
         "description":"ACME International – Main Company of the group",
         "phone":"0288396",
         "fax":"998266",
         "address":"Madison Square Garden",
         "city":"NY",
         "state":"NY",
         "country":"USA",
         "zip_code":"00195",
         "notes":null,
         "logo":"company/image/a/c/acme_usa.png",
         "primary_contact":"4\\euclid",
         "mailbox_id":"0",
         "status":"1",
         "formtemplate_id":"56",
         "updated_at":"2018-07-12 08:43:13",
         "created_at":"2018-06-19 13:30:41"
      },
      {
         "entity_id":"2",
         "parent_id":"1",
         "sort_order":null,
         "name":"ACME France",
         "description":"ACME France",
         "phone":null,
         "fax":null,
         "address":"Roux de Strasse",
         "city":"Paris",
         "state":"Paris",
         "country":"France",
         "zip_code":"75000",
         "notes":null,
         "logo":"company/image/a/c/acme_fr_1.png",
         "primary_contact":"4\\euclid",
         "mailbox_id":"0",
         "status":"1",
         "formtemplate_id":"56",
         "updated_at":"2018-07-12 08:43:56",
         "created_at":"2018-06-19 13:33:57"
      }
   ]
}
				
			

API Authentication

If you want to use Deepser API you must authenticate before using it.
The authentication supported by Deepser are currently of 2 types: the Basic Authentication and the Authentication with Token. We strongly suggest to use Token Authentication for improved security.


AUTHENTICATION WITH TOKEN

This can be done, before any request to the API, with some simple lines of code to add the Authentication parameters to the HTTP Headers.
In addition to the Basic Authentication, you have also to enable the Token for the user you want to authenticate.
To do that, you have to login into Deepser as a System Admin.
Go to the Configuration for the User you want to enable to token Authentication through API.
The menu in Deepser is System > Permissions > Users and then select the user you need to enable for token authentication.

PLEASE NOTE: If the “API Token” field isn’t visible, expose it by pressing the edit form button.

Then expose the field by using drag and drop.

You can use the three buttons to perform automatic actions on the Token: generate, delete or copy to clipboard.

From a developer’s perspective, once enabled the Token for the User, you need to set the header of the HTTP Request with the token.
In the following example, we see how to add the authentication parameter to a CURL request in PHP language:

				
					$host = 'http://deepserhost';
$process = curl_init($host);
$token="DEMO_TOKEN";
$headers = array(
'Authorization: Bearer '. $token,
'Accept: application/json'
);
curl_setopt($process, CURLOPT_HTTPHEADER, $headers);
// other lines to set the API request
…
// call the API using CURL
$return = curl_exec($process);
curl_close($process);
				
			

Where http://deepdeskhost is the address of your Deepser and token is the token generated for the user.

BASIC AUTHENTICATION

This can be done, before any request to the API, with some simple lines of code to add the Authentication parameters to the HTTP Headers.
To achieve that we need to set the header with the string ‘username’:’password’ encoded in base64 format.
In the following example, we see how to add the authentication parameter to a CURL request in PHP language:

				
					$host = 'http://deepserhost';
$process = curl_init($host);
$headers = array(
      'Authorization: Basic '. base64_encode("user:password")
);
curl_setopt($process, CURLOPT_HTTPHEADER, $headers);
// other lines to set the API request
…
// call the API using CURL
$return = curl_exec($process);
curl_close($process);
				
			

Where http://deepserhost is the address of your Deepser and user:password is your username/password.

Of course, if you prefer to use other languages, the REST technology is language-independent.
We see how to use Java to make such a call:

				
					String encoding = Base64Encoder.encode ("user:password");
HttpPost httppost = new HttpPost("http://deepserhost");
httppost.setHeader("Authorization", "Basic " + encoding);
// other lines to set the API request
…
// call the API using Java HttpRespnse
HttpResponse response = httpclient.execute(httppost);
HttpEntity entity = response.getEntity();
				
			

Now that you know how to authenticate to Deepser API, go to the next lesson to see the advanced documentation of the API.
We assume you have already read the API introduction and you have learnt all the basic concepts stated in that guide.

API Main Methods

You can access entities of Deepser, using the actions implemented by the API:

    • Create: to create a single resource (HTTP POST)
    • Retrieve: to get a single resource (HTTP GET)
    • Multiple Retrieve: to get multiple resources (HTTP GET)
    • Update: to update a single resource (HTTP PUT)
    • Delete: to delete a single resource (HTTP DELETE)

Note: Multiple Delete is not allowed for Security Reasons.

We will now explain in details every action.
In this lesson the examples are all made using the Company entity.
We assume your Deepser installation host is http://deepserhost/.
After having explored the methods, we will list a detail of entities accessible by the API.

Retrieve

HTTP Method: GET
Base Syntax:

http://deepserhost/api/rest/[entity]/[id]

Example Syntax:

http://deepserhost/api/rest/company/4

Description: retrieves the entity data, given an entity ID.
Example Result:

http://deepserhost/api/rest/company/4
				
					{
    "entity_id": "4",
    "parent_id": "1",
    "sort_order": null,
    "name": "ACME UK",
    "description": "ACME UK",
    "phone": "08567565",
    "fax": "8587575",
    "address": "Carnaigehall Street",
    "city": "London",
    "state": "London",
    "country": "UK",
    "zip_code": "10000",
    "notes": null,
    "logo": "company/image/a/c/acme_uk.png",
    "primary_contact": "4\\nobel",
    "mailbox_id": "0",
    "status": "1",
    "formtemplate_id": "56",
    "updated_at": "2018-08-01 15:04:59",
    "created_at": "2018-07-12 08:39:16",
}
				
			

Note that every custom field created in Deepser is retrieved by the API. Custom fields have the prefix cust_ before their name.
So, for example, if a user creates a field named website, the REST API will return a JSON property called cust_website.

Multiple Retrieve

HTTP Method: PUT
Base Syntax:

http://deepserhost/api/rest/[entities]?[filters]&[parameters]

Example Syntax:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&limit=2

Description: retrieves the entities data, given some filters or parameters.
Example Result:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&limit=2
				
					{
    "totalRecords": 3,
    "items": [
        {
            "entity_id": "1",
            "parent_id": "0",
            "sort_order": null,
            "name": "ACME International",
            "description": "ACME International - Main Company of the group",
            "phone": "0288396",
            "fax": "998266",
            "address": "Madison Square Garden",
            "city": "NY",
            "state": "NY",
            "country": "USA",
            "zip_code": "00195",
            "notes": null,
            "logo": "company/image/a/c/acme_usa.png",
            "primary_contact": "4\\euclid",
            "mailbox_id": "0",
            "status": "1",
            "formtemplate_id": "56",
            "updated_at": "2018-07-12 08:43:13",
            "created_at": "2018-06-19 13:30:41",
            "payment_status": null
        },
        {
            "entity_id": "2",
            "parent_id": "1",
            "sort_order": null,
            "name": "ACME France",
            "description": "ACME France",
            "phone": null,
            "fax": null,
            "address": "Roux de Strasse",
            "city": "Paris",
            "state": "Paris",
            "country": "France",
            "zip_code": "75000",
            "notes": null,
            "logo": "company/image/a/c/acme_fr_1.png",
            "primary_contact": "4\\euclid",
            "mailbox_id": "0",
            "status": "1",
            "formtemplate_id": "56",
            "updated_at": "2018-07-12 08:43:56",
            "created_at": "2018-06-19 13:33:57",
            "payment_status": null
        }
    ]
}
				
			

Where:

totalRecords is the number of items corresponding to the conditions of the query (note that is more than the limit we set).
items is a JSON array with all entities retrieved (eventually limited to the limit parameter).

FILTERS
When we deal with the multiple retrieve method, it is important to understand filters and parameters to get only a subset of data if we don’t need to retrieve all the entities of the system.

Think about filters as the where condition of a SQL Query, while parameters are clauses (limit, sort, etc.) for that query.
Deepser API filters are very simple to implement.
To define filters, just pass additional fields to the HTTP request query string.
The syntax to define filters is here described.
After the request path we define an array called filter.
This array has at least one element with key attribute to define the target field:

http://deepserhost/api/rest/companies?filter[1][attribute]=field

Where:

  • filter is our array to set filters
  • attribute is a constant key
  • field is the name of the field we want to apply the filter to

Then, we must define which kind of filter we want to apply to that field, by populating in the query string the element of the filter array with key corresponding to the kind of filter. The value of that element is the value to look for:

http://deepserhost/api/rest/companies?filter[1][attribute]=field&filter[1][operator]=value

Where:

  • filter is our array to set filters and the index 1 is the same of the attribute field we are referring to
  • operator is a key with the query operator we want to apply. Operators are described below
  • value is the value of the condition we want to apply to the filter

To filter a company by its name, taking all the companies with name starting with the string ‘ACME’, we should raise this GET request:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%

Obviously, to implement more filters on different fields we can add more elements to our filter array:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&filter[2][attribute]=country&filter[2][eq]=USA

This will filter all companies with name starting with ACME and country equals to USA.

FILTER OPERATORS

When we deal with filters, it is important to understand filter operators to create the query we need.
Here is a list of all operators that can be used:

  • eq – “equal to” – returns items with the specified attribute that is equal to the defined value
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%
  • neq – “not equal to” – returns items with the specified attribute that is not equal to the defined value
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][neq]=ACME
  • in – “equals any of” – returns items that are equal to the item(s) with the specified attribute(s)
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][in]=ACME

If we want to use multiple values for the in, we can use an additional array, so for example:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][in][0]=ACME&filter[1][in][1]=Contoso 
  • nin – “not equals any of” – returns items excluding the item with the specified attribute
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nin][1]=ACME&filter[1][nin][2]=International
  • gt – “greater than” – returns items with the specified attribute that is greater than the defined value
http://deepserhost/api/rest/companies?filter[1][attribute]=parent_id&filter[1][gt]=0
  • lt – “less than” – returns items with the specified attribute that is less than the defined value
http://deepdeskhost/api/rest/companies?filter[1][attribute]=parent_id&filter[1][lt]=1
  • like – “like” – returns items with the specified attribute is like the defined value. Use SQL like syntax to define wildcards chars.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%
  • nlike – “not like” – returns items with the specified attribute is not like the defined value. Use SQL like syntax to define wildcards chars.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%
  • from, to – “from to” – specifies the range of attributes according to which items will be returned.
http://deepserhost/api/rest/companies?filter[1][attribute]=parent_id&filter[1][from]=2&filter[1][to]=3

You can write filters using AND, OR logical operators.
To do that follow the examples:

  • AND: to define a condition in AND, simply define multiple filters, like:
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&filter[2][attribute]=parent_id&filter[2][gt]=0
  • OR: to define a condition in OR, use this syntax:
http://deepserhost/api/rest/companies?filter[1][attribute]=entity_id&filter[1][0][eq]=1&filter[1][1][eq]=3

So use multiple index arrays in the filters for the same field.

To use an OR condition on different fields, use the following syntax:

http://deepserhost/api/rest/companies?filter[1][attribute]=entity_id&filter[1][0][eq]=1&filter[1][1][eq]=3

PARAMETERS

When we deal with retrieve multiple method, it is important to understand parameters to create the query we need.
Here is a list of all parameters that can be used:

  • page: specifies the page number which items will be returned.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%&page=2
  • order: specifies the sort order of returned items.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%&order=name&dir=asc
  • dir: specifies the order direction: ‘asc’ – returns items in the ascending order; ‘dsc’ – returns items in the descending order.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%&order=name&dir=asc
  • limit: limits the number of returned items in the response. Note that by default, 10 items are returned in the response. The maximum number is 100 items.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%&limit=100

If the attribute value consists of several words separated by a whitespace, the ‘%20’ sign is used:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][eq]=ACME%20International%20LTS

Create

HTTP Method: POST
Base Syntax:

 http://deepserhost/api/rest/[entities]/

JSON Payload Syntax: a JSON object with the data to insert

Example Syntax:

http://deepserhost/api/rest/companies

Example JSON Payload Syntax:

				
					{
    "name" : "ACME Portugal",
    "description" : "ACME Portugal SA."
}
				
			

Description: creates the entity, given the payload JSON data.
Example Result:

http://deepserhost/api/rest/companies
				
					{
    "name": "ACME Portugal",
    "description": "ACME Portugal SA.",
    "created_at": "2018-10-29 15:57:42",
    "updated_at": "2018-10-29 15:57:42",
    "entity_id": "8"
}
				
			

Returns the company created, field entity_id is the ID of the new company.

Update

HTTP Method: PUT
Base Syntax:

http://deepserhost/api/rest/[entity]/[id]

JSON Payload Syntax: a JSON object with the data to update

Example Syntax:

 http://deepserhost/api/rest/company/5

Example JSON Payload Syntax:

				
					{
    "name" : "ACME Germany",
    "parent_id" : "1",
    "description" : "ACME Germany Gmbh"
}
				
			

Description: creates the entity, given the payload JSON data.
Example Result:

http://deepserhost/api/rest/companies
				
					{
    "entity_id": "5",
    "parent_id": "1",
    "sort_order": null,
    "name": "ACME Germany",
    "description": "ACME Germany Gmbh",
    "phone": null,
    "fax": "+498587575",
    "address": "Augsburger Strasse",
    "city": "Berlin",
    "state": "Berlin",
    "country": "DE",
    "zip_code": "10115",
    "notes": null,
    "logo": null,
    "primary_contact": null,
    "mailbox_id": "0",
    "status": "1",
    "formtemplate_id": "0",
    "updated_at": "2018-10-29 16:14:10",
    "created_at": "2018-10-29 15:49:33",
    "payment_status": null
}
				
			

Returns a JSON Object with all fields of the entity updated (not only updated fields, but ALL fields of that entity).

Delete

HTTP Method: DELETE
Base Syntax:

http://deepserhost/api/rest/[entity]/[id]

Example Syntax:

http://deepserhost/api/rest/company/6

Description: deletes the entity, given an entity ID.
Example Result:

http://deepserhost/api/rest/company/6
				
					// this is only in case of an error
{
    "messages": {
        "error": [
            {
                "code": 404,
                "message": "Resource not found."
            }
        ]
    }
}
				
			

If the entity is successfully deleted returns an empty response, else returns a JSON object with error messages.

API Entities

Here you are the full list of Deepser entities implemented by the API:

  • Company: the companies of Deepser.
  • User: the users of Deepser.
  • Group: the user groups of Deepser.
  • Service Operation: the operations (tickets, incidents, requests, etc.) of Deepser.
  • Service Type: the types of the operations (incidents, requests, changes, phone calls, etc.).
  • Activity: the activities (comments or worklogs) of Deepser.
  • Cmdb CI: the CIs (devices, softwares, etc.) of Deepser.

API Company

The Company entity is used to manage companies in Deepser.
Companies can be only created by Administrators that can access the Company Module.
Agents and Key Users can only retrieve the Companies.
End Users cannot access this resource via API.

Endpoints

http://deepserhost/api/rest/company/[id]
http://deepserhost/api/rest/companies

Roles

Here we list all the permissions by user role regarding the API:

 AdmininistratorAgentKey UserUser
Actions AllowedRETRIEVE
CREATE
UPDATE
DELETE
RETRIEVERETRIEVE 

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

FieldMeaning
entity_idThe unique ID to identify the record.
nameThe name of the Company, that will be displayed on the select-boxes in the system.
parent_idThe field “Parent” can contain the name of another company. If the Company has a parent, it means that we are configuring a sub-company (a branch of the main company). Think about an international corporation that has some local branches (eg: the head office is in the US and some branches in Europe). Thank to the Parent field we can create a hierarchical structure of maximum 2 levels to define companies in the system. The Parent concept can be eventually extended to more levels with a customization but the default configuration of Deepser allows 2 levels: in most cases it is enough to describe a company structure.
If we try to add more than 1 Parent level, the software returns a blocking error in the company form.
descriptionDescription of the Company.
statusIf the company is disabled it will not be displayed in the select-boxes.
mailbox_idThis field is used to define that all the emails sent to users of that organization will be sent by a specific mailbox.
This field is rarely used and has the aim to send emails to a specific company from a pre-configured email address. If not set Deepser will use the system settings to send emails: the emails will be sent from the default outgoing mailbox, or, if the record has a specific mailbox set in the field “Outgoing Mailbox”, Deepser will use the specific mailbox only for that records.
logoCompany Logo.
addressCompany Address.
cityCompany City.
stateState / Area.
countryCountry of the company.
zip_codeZip Code.
primary_contactUser of Deepser that is marked as a primary contact for that company.
phoneMain phone number.
faxFax.
notesInternal notes.
formtemplate_idThe form template ID used by the record. Please refer to the Formtemplate ID guide of Deepser Docs.
updated_atLast update date of the record.
created_atThe creation date of the record.

User API

The User entity is used to manage users that can login to Deepser.
Users can be only created by Administrators that can access the User Module.
Agents and Key Users can only retrieve the Users.
End Users cannot access this resource via API.

Endpoints

http://deepserhost/api/rest/user/[id]
http://deepserhost/api/rest/user/[id]

Roles

Here we list all the permissions by user role regarding the API:

 AdmininistratorAgentKey UserUser
Actions AllowedRETRIEVE
CREATE
UPDATE
DELETE
RETRIEVERETRIEVE 

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

FieldMeaning
user_idThe unique ID to identify the record.
avatarIcon with the user avatar. If not set, it will be chosen randomly from the system.
usernameUsername used by a user to access the software. It is the field that uniquely identifies the user.
Username is thus used for the login to Deepser. If we create manually a user, we can choose the username we want.
Obviously, user name must be unique otherwise the system will block the creation of a user with a username already in use.
If we insert users with the LDAP integration the username will be the LDAP attribute we chose when configuring the integration, but Deepser prepend a number and a backslash (\) to identify the ID of the LDAP directory from which we are importing the user.
In case of LDAP users, the login screen of Deepser will change, adding a select-box to choose the domain. This select-box is thus mandatory for the users with an LDAP account.
A user manually inserted has, for example, this username: admin or name.surname, or rather the email of the user.
A user imported from LDAP will have, for example, this username: 1\name or 1\name.surname.
Looking at the ID of the LDAP directory we can easily find from which LDAP source the user has been imported.
roleThe role of the user. Please refer to the Roles in your system to get the correct IDs.
firstnameFirst name of the user
lastnameLast name of the user
emailEmail of the user to receive notifications. Email is a very important field if we activate the email integration: Deepser send all the emails to users according to this value.
passwordPassword to log into the system. Password is encrypted in the database. If a user is an LDAP user the password will not be saved in the database, but the system will try to authenticate directly to the LDAP server.
is_activeIt tells if an user is active in the system. Non-active users are not displayed in the select-boxes of Deepser modules, cannot receive emails and cannot log into the system.
startup_pagePage to which the user is redirected after the login. This field contains a list of all the system pages.
localeLanguage of the user. Deepser has a native support to many languages. It is possibile to translate the software using this short guide: Translate Deepser
timezoneTimezone of the user. Timezone is applied when displaying the dates on the interface. Infact, in the Deepser DataBase all dates are stored referring to the system timezone: UTC. This setting allows the system to manage all the dates with consistency and not to have problem with the variaton of dates based on the location of a user.
company_idCompany of the user. All users can be part of one (and only one) company. Companies are explained in that guide: Company Guide.
Companies can be grouped in a 2 level structure: one company is the Parent and can have multiple sub-companies. That way we can manage the visibility of the requests allowing, for example, a corporate manager to see all the sub-company requests and allowing a director of a sub-company to see only data of his smaller organization.
is_supervisorIf the user is a supervisor he can see data of all users of the company (and sub-companies). This field is very important to determine which data cha see a user within his organization. If the user is a supervisor and can access the back-end (Administrator, Agent, Key-User) he can see all data of his Company and sub-companies. This is true if the user has the field Company Visibility set to Limit Data to Company. On the contrary, the user can see all data in the system.
If we talk about a user with type “User” (an end user/customer), this user can only see the data regarding his requests (and no other). But, if the user is configured as supervisor can see all the Service Operations of his Company (and sub-companies if present).
company_visibilityA user with this field set can see only data of his company (and sub-companies). If a user access the back-end this field is very useful to limit the visibility. Think, for example, to an operator that can only manage requests from his brach. If we create a company specifically for the branch and limit the data of the user to that branch, the operator will not see any other company data.
Talking about a user of type “User” this field is always ignored, because the user can only see his records and if the field Is Supervisor is set to true, then he can also see the data of his company.
formtemplate_idThe form template ID used by the record. Please refer to the Formtemplate ID guide of Deepser Docs.
modifiedLast update date of the record.
createdThe creation date of the record.
display_usernameThe username displayed in the system (typically Firstname + Lastname).

Group API

The Group entity is used to manage user groups in Deepser.
Groups can be only created by Administrators that can access the Group Module.
Agents and Key Users can only retrieve the Groups.
End Users cannot access this resource via API.

Endpoints

http://deepserhost/api/rest/group/[id]
http://deepserhost/api/rest/groups
http://deepserhost/api/rest/group/[id]/relation/users

Roles

Here we list all the permissions by user role regarding the API:

 AdmininistratorAgentKey UserUser
Actions AllowedRETRIEVE
CREATE
UPDATE *
DELETE
RETRIEVERETRIEVE 

* UPDATE not allowed for endpoint:

http://deepdeskhost/api/rest/group/[id]/relation/users

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

FieldMeaning
entity_idThe unique ID to identify the record.
nameThe name of the group displayed in the system.
descriptionDescription of the group.
emailEmail address of the group.
levelSupport level of the group
statusThe status of the group. Typically 1 is Enabled, 0 is Disabled.
company_visibilityThis is similar to company_visibility of the Users. This is a general setting used to set the visibility for all members of the group.
user_idsAn Array containing all the users of the group.
formtemplate_idThe form template ID used by the record. Please refer to the Formtemplate ID guide of Deepser Docs.
updated_atLast update date of the record.
created_atThe creation date of the record.

To get only the users in a group (without all the group information) you must use the GET method with the endpoint:

http://deepserhost/api/rest/group/[id]/relation/users

It returns an array with the IDs of the users.

To add users in a group you must use the POST method with the endpoint:

http://deepserhost/api/rest/group/[id]/relation/users

JSON Payload Syntax: a JSON array with an array of the data to insert

				
					[
    [
        21,
        22
    ]
]
				
			

To delete users from a group you must use the DELETE method with the endpoint:

http://deepserhost/api/rest/group/[id]/relation/users

JSON Payload Syntax: a JSON array with an array of the data to delete

				
					[
    [
        21,
        22
    ]
]
				
			

Service Operation API

The Service Operation entity is used to manage Operations (tickets) in Deepser.
Service Operations can be accessed by every user.

Endpoints

http://deepserhost/api/rest/service/operation/[id]
http://deepserhost/api/rest/service/operations

Roles

Here we list all the permissions by user role regarding the API:

 AdmininistratorAgentKey UserUser
Actions AllowedRETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

FieldMeaning
entity_idThe unique ID to identify the record.
type_idThe Type ID of the operation record (it is the numerical ID of the entity type: incident, request, change, etc.).
titleThe title of the operation. A brief description.
category1The category (1st level) of the operation. It is an important field to manage the assignment to working teams and to catalog correctly the scope of the activity requested.
category2The category (2nd level) of the operation. It is an important field to manage the assignment to working teams and to catalog correctly the scope of the activity requested.
category3The category (3rd level) of the operation. It is an important field to manage the assignment to working teams and to catalog correctly the scope of the activity requested.
descriptionExtended description of the request.
statusIt is the status of the operation. It is an important value to manage the lifecycle of the request.
priority_idPriority of the operation: the importance from the working team perspective.
urgency_idUrgency of the operation: the importance from the requester user perspective.
submit_usernameThe user that has created the record (he can be different from the Requester User that is the user actually requesting an activity). Think about a secretary that is submitting a request on behalf of his boss. The Submit User is the secretary, while the Requester User is the chief officer.
requester_usernameUser that is actually requesting a service.
assigned_group_idWorking team that is working to solve the request.
assigned_usernameUser that has taken in charge the request. He is typically an Agent or a Key User. Deepser lets you assign also to end users if we decide that they can be part of the resolution process.
created_atCreation date of the record.
updated_atDate of the last update on the system.
closed_atClosing date of the record. If a record changes status from closed to re-opened, the this date is reset to null.
archivedEvery Operation can be archived, for example we can archive all closed Operations of the past 5 years to hide them in the standard grids (but we could see them in the Archived grid).
archived_atArchived date of a request.
updated_byThe user that has lat updated the request.
deletedEvery Operation can be deleted setting the status to “Deleted” (or other status belonging to the Deleted class). All deleted requests will not be physically deleted from the database, but they will be only marked as deleted (soft delete, so they will be visibile in the Deleted grid). To delete physically use the button “Delete”. The record will not be recoverable anymore.
deleted_atDeleted date of the request.
mailbox_idThe mailbox that will be used to send notifications regarding the Operation. If empty the default outgoing mailbox will be used (if set).
due_dateThe agreed date for the resolution.
versionThe version of the request. Deepser stores in its DataBase every version of the Operations. We can always know the changes, the user that made a change and the date.
solutionThe solution of a request, that can be emailed to the requester user or exposed on the portal.
formtemplate_idThe formtemplate id of the record.

Service Type API

The Service Type entity is used to manage the type of Operations in Deepser (eg: Incidents, Tickets, Requests, Phone Calls, etc.).
Service Types can be defined or updated only in the Deepser interface.
Service Types can be only retrieved by Administrators, Agents or Key Users via API.
End Users cannot access this resource via API.

Endpoints

http://deepserhost/api/rest/service/type/[id]
http://deepserhost/api/rest/service/types

Roles

Here we list all the permissions by user role regarding the API:

 AdmininistratorAgentKey UserUser
Actions AllowedRETRIEVERETRIEVERETRIEVE 

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

Here we list all the fields of the entity to describe their meainings in Deepser:

FieldMeaning
entity_idThe unique ID to identify the record.
nameThe Name of the Type (eg: Incident, Request, Change, etc.).
descriptionThe description of the Type.
iconThe icon of the Type.
positionThe order in which are displayed the Types.
status1 if the Type is Enabled, 0 if it is Disabled.
formtemplate_idThe formtemplate ID of the record.
created_atCreation date of the record.
updated_atDate of the last update on the system.

Activity API

The Activity entity is used to manage all the comments and worklogs in Deepser.

Activities can be accessed by all user Roles in the API.

Activities API access changes based on the Main Model (model_alias) the Activity is referring to.

Activity entities are supported for these models:

Model name

Model alias

Operation

deep_service/operation

Account

deep_crm/account

Device

deep_asset/device

Quote

deep_sales/quote

Contract

deep_contract/contract

Ci

deep_cmdb/ci

 

GET Endpoint

This endpoint retrieves the entity data that has the specified values.

 

For this endpoint we have 3 mandatory fields:

  • activity_id, that contains the id of the activity I want to retrieve.
  • model_alias, that contains the model that relates to that specific activity.
  • model_id, that contains the id of the model that this activity relates to.

 

 

HTTP Method: GET
Base Syntax:

				
					http://deepserhost/api/rest/activity/activity/[activity_id]?model_alias=[model_alias]&id=[model_id]
				
			

Example Syntax:

				
					http://deepserhost/api/rest/activity/activity/234?model_alias=deep_service/operation&id=196
				
			

Example Result:

				
					http://deepserhost/api/rest/activity/activity/234?model_alias=deep_service/operation&id=196
				
			
				
					{
    "entity_id": 129,
    "type": 1,
    "description": null,
    "portal_visibility": 0,
    "frontend_visibility": 0,
    "started_at": null,
    "ended_at": null,
    "duration": null,
    "contract_id": 0,
    "contract_line_id": 0,
    "contract_line_qty": "0.0000",
    "created_by": "admin",
    "model_alias": "deep_service/operation",
    "model_id": 90,
    "status": null,
    "formtemplate_id": 0,
    "disable_routing": 0,
    "updated_at": "2023-07-05 08:55:49",
    "created_at": "2023-07-05 08:55:49"
}
				
			

PUT Endpoint

This endpoint updates the entity data specified in the body of the request as JSON that has the specified values.

 

For this endpoint we have 3 mandatory fields:

  • activity_id, that contains the id of the activity I want to update.
  • model_alias, that contains the model that relates to that specific activity.
  • model_id, that contains the id of the model that this activity relates to.

 

HTTP Method: PUT
Base Syntax:

				
					http://deepserhost/api/rest/activity/activity/[activity_id]?model_alias=[model_alias]&id=[model_id]
				
			

Example Syntax:

				
					http://deepserhost/api/rest/activity/activity/234?model_alias=deep_service/operation&id=196
				
			

Example Syntax:

				
					http://deepserhost/api/rest/activity/activity/234?model_alias=deep_service/operation&id=196
				
			

Body of the request:

				
					{
    "description": "Test Description"
}

				
			

Please make sure that the key of the JSON data matches the field code of the entity that you want to update otherwise it will not be updated. In this case we will update the description field of this entity.

The response of this API call will be the updated version of the entity.

				
					{
    "entity_id": 128,
    "type": 2,
    "description": "Test Description",
    "portal_visibility": 0,
    "frontend_visibility": 0,
    "started_at": "2023-02-07 11:15:00",
    "ended_at": "2023-02-07 12:30:00",
    "duration": 4500,
    "contract_id": 1,
    "contract_line_id": 1,
    "contract_line_qty": "0.0000",
    "created_by": "demo.key.user",
    "model_alias": "deep_service/operation",
    "model_id": 90,
    "status": 1,
    "formtemplate_id": 45,
    "disable_routing": 0,
    "updated_at": "2023-07-05 08:28:45",
    "created_at": "2023-02-07 11:34:00"
}

				
			

POST Endpoint

This endpoint creates a new Activity entity with data given in the body of the request as JSON that has the specified model_alias and operation_id.

 

For this endpoint we have 2 mandatory fields:

  • model_alias, that contains the model that relates to the activities I want to create.
  • model_id, that contains the id of the model that this activity will relate to.

 

 

HTTP Method: POST
Base Syntax:

				
					http://deepserhost/api/rest/activity/activities?model_alias=[model_alias]&id=[model_id]
				
			

Example Syntax:

				
					http://deepserhost/api/rest/activity/activities?model_alias=deep_service/operation&id=196
				
			

Example Result:

				
					http://deepserhost/api/rest/activity/activities?model_alias=deep_service/operation&id=196
				
			

Body of the request:

				
					{
    "type": 1,
    "description": "Test Description",
    "portal_visibility": 0,
    "frontend_visibility": 0
}

				
			

Please make sure that the keys of the JSON data match the field codes of the entity that you want to create otherwise the entity will be created with only the corresponded fields. In this case we will create a new Activity with the given data in the body of the request.

 

The response of this API call will be the updated version of the entity.

				
					{
    "type": 1,
    "descritpion": "Test Description",
    "portal_visibility": 0,
    "frontend_visibility": 0,
    "model_alias": "deep_service/operation",
    "model_id": 90,
    "created_by": "admin",
    "created_at": "2023-07-05 09:00:30",
    "updated_at": "2023-07-05 09:00:30",
    "entity_id": 130
}

				
			

DELETE Endpoint

 

This endpoint Deletes the entity that has the specified activity_id, model_alias, model_id.

 

For this endpoint we have 3 mandatory fields:

  • activity_id, that contains the id of the activity I want to delete.
  • model_alias, that contains the model that relates to that specific activity.
  • model_id, that contains the id of the model that this activity relates to.

 

 

HTTP Method: DELETE
Base Syntax:

				
					http://deepserhost/api/rest/activity/activity/234?model_alias=deep_service/operation&id=196
				
			

Example Syntax:

				
					http://deepserhost/api/rest/activity/activities?model_alias=deep_service/operation&id=196
				
			

Example Result:

				
					http://deepserhost/api/rest/activity/activity/234?model_alias=deep_service/operation&id=196
				
			

This method doesn’t return any response.

 

 

Load multiple entities Endpoint

This endpoint retrieves all entities that have the specified model_alias and model_id.

 

For this endpoint we have 2 mandatory fields:

  • model_alias, that contains the model that relates to the activities I want to retrieve.
  • model_id, that contains the id of the model that these activities relate to.

 

HTTP Method: GET
Base Syntax:

				
					http://deepserhost/api/rest/activity/activities/?model_alias=[model_alias]&id=[model_id]
				
			

Example Syntax:

				
					http://deepserhost/api/rest/activity/activities/?model_alias=deep_service/operation&id=196
				
			

Example Result:

				
					http://deepserhost/api/rest/activity/activities/?model_alias=deep_service/operation&id=196
				
			

The response:

				
					{
    "totalRecords": 7,
    "items": [
        {
            "entity_id": 124,
            "type": 1,
            "description": "<p>Dear user, I kindly ask you to give us a date to get your computer.<br />The technician is available tomorrow at 2 pm or the day after tomorrow at 3 pm.<br /><br />Thank you.</p>",
            "portal_visibility": 1,
            "frontend_visibility": 0,
            "started_at": null,
            "ended_at": null,
            "duration": null,
            "contract_id": 0,
            "contract_line_id": 0,
            "contract_line_qty": "0.0000",
            "created_by": "admin.demo",
            "model_alias": "deep_service/operation",
            "model_id": 90,
            "status": null,
            "formtemplate_id": 44,
            "disable_routing": 0,
            "updated_at": "2023-02-07 10:41:35",
            "created_at": "2023-02-07 10:41:35",
            "create_by_data": {
                "username": "admin.demo",
                "display_username": "DEMO ADMIN",
                "avatar_url": "https://kevin.deepser.net/media/user/image/default/12.png"
            },
            "created_at_date": "7/2/2023 10:41 AM"
        },
        {
            "entity_id": 125,
            "type": 1,
            "description": "<p>I prefer tomorrow at 2PM.</p>\r\n<p>Thank you.</p>",
            "portal_visibility": 1,
            "frontend_visibility": 0,
            "started_at": null,
            "ended_at": null,
            "duration": null,
            "contract_id": 0,
            "contract_line_id": 0,
            "contract_line_qty": "0.0000",
            "created_by": "user",
            "model_alias": "deep_service/operation",
            "model_id": 90,
            "status": null,
            "formtemplate_id": 44,
            "disable_routing": 0,
            "updated_at": "2023-02-07 10:43:14",
            "created_at": "2023-02-07 10:43:14",
            "create_by_data": {
                "username": "user",
                "display_username": "Demo User",
                "avatar_url": "https://kevin.deepser.net/media/user/image/default/9.png"
            },
            "created_at_date": "7/2/2023 10:43 AM"
        }
]
}

				
			

CMDB CI API

The CMDB CI entity is used to manage all CIs in Deepser (devices, softwares, contracts, etc.).
CIs can be created by Administrators, Agents and Key Users.
End Users cannot access this resource via API.

Endpoints

http://deepserhost/api/rest/cmdb/ci/[id]
http://deepserhost/api/rest/cmdb/cis

Roles

Here we list all the permissions by user role regarding the API:

 AdmininistratorAgentKey UserUser
Actions AllowedRETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE
DELETE
RETRIEVE
CREATE
UPDATE
DELETE
 

Fields

Here we list all the fields of the entity to describe their meainings in Deepser:

FieldMeaning
nameThe name of the CI. Usually a brief description.
type_idThe type of the CI. It is a very important value to manage the organization of the CMDB.
class_idThe Class the CI belongs to.
subtype_idThe Subtype of the CI. It is a very important value to manage the organization of the CMDB.
category1The category (1st Level) of the CI. It can be used according to the category of the Service module, in order to link Operations and CIs.
category2The category (2nd Level) of the CI. It can be used according to the category of the Service module, in order to link Operations and CIs.
category3The category (3rd Level) of the CI. It can be used according to the category of the Service module, in order to link Operations and CIs.
descriptionLarge description of the CI.
statusThe status of the CI. It is an important value to manage the lifecycle of the element.
priority_idPriority of the CI from the operator perspective.
urgency_idUrgency of the CI from the requester user perspective.
business_impact_idBusiness Impact of the CI from the organization perspective. If a CI is not available, the business impact represents the enormity of the situation and can be in terms of people, finances, systems, etc. For example, it can describe: the number of people affected by the CI outage or the potencial financial losses, or the number of other systems affected.
serial_numberThe serial number of the CI.
notesLarge Notes field.
front_imageThe main image of the CI.
back_imageThe back image of the CI. For example, if the CI is a rack, we can take a photo of the back side in order to see the connections or the cables.
assigned_company_idCompany that has taken in charge the CI. It is typically a Service Provider Company that has to monitor the CI. This field is very important to give the right visibility on the CIs. If a user has company restricted visibility, he cannot see CIs of other companies. Notice that a user with restricted company visibility can always see both CIs with its company in the Assigned Company OR Owner Company field.
assigned_group_idUser Group that has taken in charge the CI. It is typically a Service Provider Group of agents/key users that has to monitor the CI. This field can be left blank if there is no specific group assigned to the CI, otherwise it can be used to restrict permissions to groups.
assigned_usernameThe users who has taken in charge the CI. It is typically a Service Provider agent/key user that has to monitor the CI. This field can be left blank if there is no specific user assigned to the CI, otherwise it can be used to restrict permissions to single users.
owner_company_idCompany that is the owner of the CI. It is typically a Customer Company that uses the CI. This field is very important to give the right visibility on the CIs. If a user has company restricted visibility, he cannot see CIs of other companies. Notice that a user with restricted company visibility can always see both CIs with its company in the Assigned Company OR Owner Company field.
owner_group_idUser Group that owns the CI. It is typically a Customer or User Group of end users that can open requests on the CI. This field can be left blank if there is no specific group that owns the CI, otherwise it can be used to restrict permissions to groups (eg: when a user submits a request it could link only CIs owned by his user group).
owner_usernameUser that owns the CI. It is typically a Customer or end user who can open requests on the CI. This field can be left blank if there is no specific user that owns the CI, otherwise it can be used to restrict permissions to users (eg: when a user submits a request it could link only CIs owned by himself).
versionThe version of the CI. Deepser stores in its DataBase every version of the CIs. We can always know the changes, the user that made a change and the date.
created_atCreation date of the record.
updated_atDate of the last update on the system.
updated_byThe user that has lat updated the CI.

SSO Deepser Configuration

SSO (Single Sign On) is the technology that allows you to use delegated authentication to access Deepser.

In Deepser you can configure the sso using “Google” or “Azure” as the preconfigured provider.

Alternatively, you can also configure other delegated authentication providers using the Client OAuth configurations, but in this case you will need to manually configure the authentication parameters.

Configure SSO

To configure a new ss integrationor you will need to go to the System > Tools > OAuth > Client menu

Here you will need to click on the “Add Client” button:

As a first step you will need to assign a name to the client and click on the “Save” button to get the “Redirect Uri” that will be needed to configure the provider->side SSO.

After that, you can continue the configuration.

In the screen that will open you will be able to implement the configurations to implement SSO.

Below are the fields with their meaning:

Field

Description

Name

Identification name of the OAuth Client

Status

This is the status of OAuth Client, enabled or disabled

Provider

OAuth provider. This field can take 5 values: Google, Azure, Generic, Datto RMM, NinjaOne. In case this field is set to Google or Azure it will be possible to ignore the configuration of the fields: {{Insert list of fields already configured}}. If the field is configured to Generic you will need to manually specify the configuration of the fields.

Type

This field contains all the types that a provider can have. The values present depend on the selected provider.

Tenant ID

Required for Azure provisioning provider

 

Client ID

This field must be enhanced with the client id that will be provided by the Delegated Authentication provider.

Client Secret

This Field must be configured with the client secret that will be provided by the delegated authentication provider.

Scope

This field indicates the scopes to which the client will request access to the resources. This is visible only for Generic provider.

Url Authorize

Authorization url. this parameter is the endpoint to call to obtain authorization this parameter must be provided by the authentication provider. This is visible only for Generic provider.

Url Access Token

It is the ‘URL base’ to which the parameters are added to request the authentication token (post-authorization step). You do not need to compile it for Google or Azure providers, the default values will be used. This is visible only for Generic provider.

Url Resource Owner Details

Base url of the server responsible for managing resources. This parameter must be formed by the provider. This is visible only for Generic provider.

Proxy

This field, if enhanced, will use the proxy indicated to forward requests for Delegated authentication. This is visible only for Generic provider.

Verify

If you have configured a proxy you can enable or disable SSL check. You do not need to compile it for Google or Azure providers, the default values will be used. This is visible only for Generic provider.

Scope Separator Char

Scope separator character, indicates which character the provider uses to indicate the end of one scope and the beginning of another.

At this point the client verification key will be displayed, it will be necessary to click the validate button.

At the end of this configuration, you will need to click on the “Apply” button

You will then be redirected to the login screen of the Delegated authentication provider you are configuring.

At the end of the wizard if everything went well you will be redirected to the Deepser OAuth client screen with a message that will indicate that the configuration has taken place successfully.

In case of errors on the same page the error message will appear at the top.

USER TAB CONFIGURATIONS

In this tab are the configurations related with the users either in the linked provider and in Deepser

Below are all the fields available in this section:

Field

Description

Related LDAPs

You can select one or more options from Public OpenLDAP ForumSys, Public OpenLDAP Debian.

Username Attribute

Specify which user data attribute will be used to create the username.

User Data Source

Select one of the options: Endpoint or ID Token (JWT)

Endpoint User Data

Additional information for EndPoint user data source

User fields On Creation

Is a mapping between the user fields in Deepser and the related Provision. This will be used on sign up with selected Provider or when is the first time of provision for the specific user.

User Create Expression

Is a field that accepts PHP script to do the mapping between the user fields in Deepser and the related Provision. This will be used on sign up with selected provider or when is the first time of provision for the specific user.

The default variables are:
$user => user array
$oauthUser => OAuth user array

User fields On Update

Is a mapping between the user fields in Deepser and the related Provision. This will be used every time a user signs in with the selected Provider.

User Update Expression

Is a field that accepts PHP script to do the mapping between the user fields in Deepser and the related Provision This will be used every time a user signs in with the selected Provider.

The default variables are:
$user => user array
$oauthUser => OAuth user array

Login Button Disabled

Is used to hide the login button related with the selected Provider

Login Button Caption

Is used to change the text inside the login button

Login Button Icon

Is used to change the icon inside the login button

CONFIGURE PROVISIONING 

The Provisioning functionality allows you to automatically create in Deepser the users and groups registered within your Microsoft Azure environment, if the latter have been enabled for the SSO application. 

Therefore, instead of being created/updated only at each login, it is possible to perform a synchronization between the users present in Azure who must log into Deepser, and the related User records in Deepser.  

This functionality can be performed only once, by clicking on the “Provision” button at the top right (mainly used for testing the configuration), or even be scheduled to run several times a day by configuring the Cron expression. 

To configure this functionality in Deepser, in addition to what is seen in the “Configure SSO” section, within an Azure SSO client, it will be necessary to go to the “Provisioning” tab and configure the necessary parameters. 

 

Below are the fields with their meaning: 

Field 

Description 

Provisioning enabled 

If toggled on, provisioning is enabled 

Provisioning Provider 

If “Azure” is selected,  some fields will be available

Cron Expression 

If “Azure” is selected, some specific fields will appear and others will become required 

User Provisioning Mode 

You can select the way in which users will be synchronized. Required for Azure provisioning provider. 

Disable Users 

If toggled on, local user status will be updated with provisioned user status. 

Disable Deleted Users 

If enabled, if the provided user has been deleted, or does not match the filters, or is removed from the users assigned to the application, disables the relative users in Deepser. 

User Filter 

If provisioning provider is Azure, write filters in query string format, ie: 

$filter=surname eq ‘Foo’ 

$filter=jobTitle eq null 

$filter=userPrincipalName in (“Foo”,”Bar”) 

$search=”surname:Foo” 

For documentation, see Microsoft Graph documentation 

User Group Filter 

Only provision users which are members of these specific groups. 

Groups are filtered by the field specified in Group Name Attribute 

Group Name Attribute 

Specify which group data attribute will be used as the name of the group. 

It is also the name of the group attribute to filter by in the User Group Filter and in the Group Filter.If no value is provided: Azure provisioning provider, will use displayName by default. 

Group Provisioning Mode 

You can select the way in which groups will be synchronized. Required for Azure provisioning provider. 

Group Provisioning Enabled 

If toggled on, groups will also be synchronized. 

Deepser Fundamentals

This course will cover everything you should know to start doing advanced configuration in Deepser.
We will talk about UI, Grids, Forms and the two Possible portals.

Articles

  • Deepser Backend
  • Deepser User Menu
  • Deepser Navigation Menu
  • Global Search Usage
  • Deepser Home Page
  • Grids
  • Filters and Order
  • Export Data
  • Mass Action
  • Mass Action Configuration
  • Grid Creation and Cloning
  • Configuring Grids
  • Advanced Collection Configuration
  • Grids Render and Options Configuration
  • Grids Custom Options Configurations
  • Grids Renderer Tooltip Example
  • Grids Renderer Link Example
  • Grids System Configuration
  • Form Template Theory
  • FormTemplates
  • FormTemplates Structure and Buttons
  • Form Template Selection and Creation
  • Form Template Configuration
  • Form Template Structure Configuration
  • Formtemplates Fieldset Configuration
  • Formtemplates Buttons Configuration
  • Formtemplates Field Configuration
  • Advanced Form Template Rules
  • Custom Button Configuration
  • Buttons Conditional Hiding
  • User Portal
  • Browsing the user portal
  • Managing Tickets in The User Portal
  • User Portal Additional Features
  • Configuring Portal Groups
  • Configuring Portal Requests
  • Configuring Service Operations in the User Portal
  • Enabling Other Modules in the User Portal
  • Enabling Other Modules in the User Portal Grid
  • Guest Portal
  • Enabling the Guest Portal
  • Guest Portal Visibility Configuration Overview
  • Enabling Service Types on the Guest Portal
  • Adding a Portal Group in the Guest Portal
  • Adding a Portal Request in the Guest Portal
  • Editing Form Templates in the Guest Portal
  • Enabling Categories in the Guest Portal
  • Enabling Notifications for Guest Users
  • Knowledge Base in the Guest Portal
  • CMS in the Guest Portal
  • Cache Management
  • Quick Reply
  • Mentions
  • Module Creator - Creating a custom module

Deepser Backend

The back-end screen of Deepser is organized into areas.

  • In the upper left area (1) there’s the User Menu.
  • In the left area (2) there’s the Navigation Menu, where we can find all the modules accessible from the back-end.
  • In the upper area (3) there’s the Global Search bar.
  • The textbox in that bar allows a full-text search on all the elements of the system. The rule is that the search is on the most important fields of every records: user name, title of an activity, name of the company, etc.
  • In the central area (4) there’s the Main Screen.

Note: the back-end is accessible only by Administrators, Agents and Key Users. End Users can only login to the User Portal.

Deepser User Menu

The User Menu of Deepser contains all the links to edit the user profile.

Below the icon with your avatar and name, clicking on the arrow, you can expand the menu:

The items of the menu are:

  • My Account: link to the page with all informations about the current logged in user, where he can modify his personal information: avatar, language, timezone, etc.
  • Portal: link to the End User Portal. A user that access the back-end can surf the User Portal by clicking this link.
  • Log Out: to disconnect from the system.
  • Help: link to the on-line help.

Deepser Navigation Menu

STRUCTURE

The Navigation Menu of Deepser contains the main links to the modules that compose the software.

Using this menu it is possible to access all the screens of the main functions of the software back-end portal.

The Navigation Menu has 2 main sections:

  • Menu items visibile to all users: they are the modules in which a user can manage Activities, Requests, CMDB, take a look at the Dashboard, etc.
  • System item: only a user with role Administrator can access this item.

The Navigation Menu is different from user to user, based on the user permissions:

  • Role: a user with role Administrator can access al the modules, even the configuration modules. A user “Agent” or “Key-User” cannot access the configuration module items (the menu System). A User (End User) cannot access to the back-end.
  • Module Visibility: a user with role Agent or Key-User can see only certain modules. This is possibile thanks to the ACL (Access Control Lists) configuration of Deepser.

The items in the Navigation Menu can contain sub-menus. In this case Deepser adds an icon on the lower corner of the menu item:

By clicking on the item with that icon we can expand the sub-menu, with other items, eventually expandable themselves:

If we select an item with no sub-menu the Main Screen of Deepser will be redirected to the main screen of the chosen module.

 HIDE NAVIGATION MENU

To make the use of the tool faster, it is possible to hide the Navigation Menu and to expand the main screen.

To hide the navigation menu click on the blue button near the global search textbox.

Global Search Usage

The Global Search Bar lets you easily find all records in the system: for example and Activity, a Support Request, a User, a Customer, a File Attachment, etc.

The Global Search textbox compares the text in it with the unique ID and the name of the entity and returns a list of all possible matches (if the record doesn’t have a Name field then another identification field is compared, for example a file name of an attachment or a title of an appointment).

Near the Global Search Bar, the blue button lets you hide the Navigation Menu, expanding the Main Screen.

Deepser Home Page

The Home Page of Deepser contains all the information regarding the module selected in the Navigation Menu.

By default, the first screen showed to a backend user after the login is the Dashboard, where you can see the graphs to easure the quality of your service real-time.

Note: The initial page of a backend user can be changed by system administrators.

To understand the details, the functions and the structure of the Home Page of Deepser, we will take a look at the Service Module.

Click on the item “Service” in the Navigation Menu on the left, we will see the sub-menus with all the Service Types in the system.

Note: the item “All” is always present and it is used to access all the Requests, without filtering the Service Types.

Selecting a menu item, the main screen of Deepser will show a grid with the requests (Operations) in the system and visibile based on the current user’s permissions.

Grids

GENERAL OVERVIEW

In Deepser data are displayed via grids.

Deepser’s grids are very flexible, however, thanks to the native features of customization, sorting, filter records in them.

Deepser allows you to manage entities values directly from the grids, without even opening the relative form, through the help of Mass Action preconfigured (or configurable).

Each grid can also be exported in *. xlsx or *. csv format in order to consult their data outside Deepser.

Filters and Order

FILTERS

In Deepser you can filter the records inside the grids according to the values of one or more fields displayed as columns.

The available filters are located immediately below the grid column header.

The way in which the filter is defined on the column values depends on the type of the field:

  • Text box
  • Date Range
  • Numerical range
  • Select-box with single selection
  • Multiple selection select-box

Once the filters have been set, to apply them to the grid, click on the Search button at the top right.

To remove the filters applied to the grid instead, click on the Reset filters button on the other right next to the Search button.

ORDERING

In Deepser you can sort records in grids by the value of any field (grid column).

To sort, simply click on the column header.

At the first click the direction of the order will be increasing, at the second click the records will follow a decreasing order.

Export Data

In Deepser all grids can be exported in *.xlsx or *.csv format.

This makes it possible to consult the data even outside the application.

The export keeps the filters and sorting applied to the grid at that time.

To export the grid you must first choose the format of the file that will be produced, by default XLSX will be proposed, from the select-box in the middle of the page, above the grid.

To download the export file, click on the download icon to the right of the chosen format.

At this point, before generating the file for download, the system will ask if you want to export only the visible records, or all the records from the other pages where the records have been divided.

Once you have decided which records should be exported, clicking one of the two modal’s buttons will start downloading the file.

Mass Action

USING MASS ACTION

In Deepser it is possible to operate on the entities visualized in a grid directly from the grid itself, through some massive actions preconfigured.

To use this feature you need to check, through the check-box in the leftmost column of the grid, the record(s) on which you want to perform the action, or use the short cut(s) of quick selection/de-selection.

 

Once the records have been selected, from the Actions select-box at the top right, select the action to perform.

Clicking the Submit button, to the right of the Actions select-box, will execute the selected mass action on the ticked records.

 

EXAMPLE: PRIORITY CHANGE

In the following example we will use the mass action Modify Priority on some service operations in grid

Step 1. Record selection

 

Step 2. Mass action selection

 

Step 3. Selecting the new value Priority

 

Step 4. Performing mass-action

 

As you can see the values of the selected records have been changed by the mass action.

 

Mass Action Configuration

In Deepser it is possible to define, through custom code, actions to be executed on the records of a grid in a massive way.

To define mass actions, from the grid configuration menu check the check-box to enable mass-actions and click on the icon </> to display the scripting area.

EXAMPLE 1 – MASS ACTION WITH SELECT

In this example we want to configure a Mass Action, in CMDB module grid, to massively change CIs’ Status.

				
					// retrieve all states from the list cmdb_ci_status as associative arrays
$statusArray = Deep::helper('deep_list')->loadListValues('cmdb_ci_status')->toOptionHash();
// initialize html component
$this->addMassActionItem('status', [
    'label'      => Deep::helper('deep_cmdb')->__('Stato'),
    'additional' => array(
        'status' => array(
            'name'   => 'status',
            'type'   => 'select',
            'class'  => 'required-entry',
            'label'  => Deep::helper('deep_cmdb')->__('Status'),
            'disable_js_select' => true,
            'values' => $statusArray,
        )
    ),
    //callback is the method that contains the logic of the action
    'callback' => function() {
        /** @var Deep_Grid_Model_Grid_Massaction_Callback $this */
        /** @var Mage_Core_Model_Resource_Db_Collection_Abstract $collection */
        $collection = $this->getGrid()->getModelInstance()->getCollection();
        //$this->getIds() returns the id of the selected cis
        $collection->addFieldToFilter('entity_id', ['in' => $this->getIds()]);
        // $collection contains the instances of the selected cis and we iterate on them
        foreach($collection as $ci){
            //$this->getValue() contains the id of the new status, the selected one
            //set the new ci status
            $ci->setStatus($this->getValue());
            //save the ci
            $ci->save();
        }
    }
]);
				
			

EXAMPLE 2 – MASS-ACTION WITH DATE-PICKER

 In this example we want to configure a Mass Action, on a grid in Operation module, to massively set the Date Expiration of service operations.

				
					//retrieve the icon that will open the date-picker
$img = Deep::getDesign()->getSkinUrl('images/grid-cal.gif');
$this->addMassActionItem('due_date', [
    'label'      => Deep::helper('deep_service')->__('Due Date'),
    'additional' => array(
        'due_date' => array(
            'name'   => 'due_date',
            'type'   => 'date',
            // define the date format
            'format'   => 'yyyy-M-d',
            'image' => $img,
            'gmtoffset' => true,
            'label'  => Deep::helper('deep_service')->__(''),
            'disable_js_select' => true,
            'build_on_load' => true,
        )
    ),
    //callback is the method that contains the logic of the action
    'callback' => function() {
        $collection = $this->getGrid()->getModelInstance()->getCollection();
        //$this->getIds() returns the id of the selected operations
        $collection->addFieldToFilter('entity_id', ['in' => $this->getIds()]);
        // $collection contains the instances of the selected operations and we iterate on them
        foreach($collection as $operation){
            //$this->getValue() contains the new date that has to be set
            //set the new due date
            $operation->setDueDate($this->getValue());
            //save the operation
            $operation->save();
        }
    }
]);
				
			

Grid Creation and Cloning

In Deepser you can create new grids, and configure them appropriately, in order to respond immediately to the needs of the agents who will work on it.

CREATING A GRID

To create a new grid, starting from zero, we have to follow only two simple steps:

Step 1

Click the New icon, circled in the figure, in the lower left area of the grid menu.

Otherwise you can also create a new grid by clicking on the icon circled in the following screeshot, next to the badge containing the name of the current grid, to display the menu.

Then click on New Grid

Step 2

The system will now ask you to enter a name for the new grid.

Once you have entered the name, click the Save button.

At this point the new grid will be created and can be selected from the grid menu.

As we can see from the following screenshot a new grid has no exposed columns (visible columns) and therefore appears “empty”. In this case it will be necessary to configure them manually.

CLONING A GRID

The grid cloning function allows you to create new grids by cloning the configuration of an existing grid.

Step1

Once positioned on the grid you want to clone, click the Clone icon, circled in the figure, at the bottom right of the grid menu.

Otherwise you can also clone a grid by clicking on the circled icon in the screenshot below to display the menu.

Then click on Clone Grid

Step 2

The system will now ask in which section of the current module should be saved.

Once selected from the select section, click the Save button.

Note: — is the option that indicates the All section.

At this point the new grid will be created and can be selected from the grid menu.

As we can see from the following screenshot the clone grid is composed by the name of the “original” grid with the addition of the prefix NEW- .

The new grid will have the same exposed columns (visible columns) as the original one, all other possible configurations will be copied as well.

Deleting  a Grid

To Delete a grid, go to the desired grid and click on it (1) and afterwards click on the edit icon(2)

Once the grid editing menu is open, click on the “Delete” button located in the bottom right corner of the window.

Configuring Grids

In Deepser you can configure grids to meet the needs of the Agents, with the aim of facilitating operations as much as possible by creating a useful and immediate interface.

To access the configuration menu of a grid, once positioned on the grid you want to modify, click the pencil icon next to the badge with the name of the current grid.

VISIBLE COLUMNS MANAGEMENT

To make a column visible in a grid, simply drag and drop it from the available columns (on the left) to the visible columns (on the right).

To remove a column from the grid simply do the opposite operation, i.e. drag&drop it from the visible columns (on the right) to the available columns (on the left).

COLUMN CONFIGURATION

To change the configuration of a single column, once selected among the visible columns (by clicking on it) its configuration menu will appear.

HEADER

Through this field you can change the column header as it is displayed in the grid.

TYPE

Indicates the type of data showed in the column.

It is related to the type of field element that the column displays. (For further information see the lesson related to custom fields)

FILTER

Checking this option makes a column filterable.

MULTI-FILTER

By checking this option you can define multiple values in the column filter.

This option only affects Select and Option types

SORTABLE

By checking this option the grid can be sorted according to the column values.

OTHER CONFIGURATIONS

In the area to the right of the grid configuration menu there is a section containing other configuration tools

GRID NAME

In this field we can specify the name of the grid.

PREPARED COLLECTION

Using the Query Builder it is possible to define filters on the data while it is being retrieved from the database, which cannot be removed using the Filter Reset button. E.g.: you want to create a grid containing service operation not in Closed state.

MASS ACTION

Through the check-box you can define whether mass-actions should be enabled in the grid.

ENABLE EXPORT

Through the check-box it is possible to define the grid to be exported or not.

GROUPS VISIBILITY

List of groups for which to make the grid visible.

Note: Super Admin users will see all grids.

Advanced Collection Configuration

In Deepser you can define, through custom code, filters on the collection of data shown in the grid.

This feature is useful when you want to define advanced conditions that cannot be expressed by query builder.

To define custom conditions on the collection, from the grid configuration menu click on the icon </> to view the scripting area.

 

Inside it you can insert the PHP code to handle on the data collection through the related query.

EXAMPLE

In this example you want to configure a custom filter on the Collection of service operations recovered from the database.

Through this filter only the service operations assigned to the groups of which the user is a member will be retrieved.

				
					// Deep::helper('deep_admin')->getCurrentUser() returns the current user object instance
// getGroupIds() returns entity_ids of of the groups of which the current user is a member
$currentUserGroups = Deep::helper('deep_admin')->getCurrentUser()->getGroupIds();
// modify the where clause of the query by adding our condition
$this->getCollection()->getSelect()->where("main_table.assigned_group_id IN (" . implode($currentUserGroups,',')
				
			

Grids Render and Options Configuration

In Deepser you can define, through PHP code, Renderer custom for each column of the grid, and the domain of the possible Options type columns.

To configure these two components, from the configuration of a grid, after selecting the column to modify, just click on the icon </> to display the two scripting areas, within which you can enter your code.

Grids Custom Options Configurations

In this example we want to define the domain of the possible options of an Options column.

A typical case in which you want to define “manually” the options of a column is the one in which a field, is the Device field of service operations.

In fact, this custom field appears as select in the form and allows you to associate a ticket to a ticket from the Devices class.

When this field is displayed in grid, the CI entity_id will be displayed and not its name.

In order to display its name in grid and use a select filter, it is necessary to properly configure the column.

To achieve this it is necessary to access the grid configuration page and set the column type to ‘Options’ and then insert some PHP code in the ‘Options’ scripting area.

Insert the following code inside the scripting area:

				
					//retreive of the CI collection
$ciCollection = Deep::getResourceModel('deep_cmdb/ci_collection');
//filter in the Clause where of the query to retrieve only Devices class ICs
$ciCollection->addFieldToFilter('class_id',['eq'=>2]);
//convert the collection into an associative array
//the keys is the CI Id and the value the CI Name
$optionsArray = $ciCollection->toOptionHash();
return $optionsArray;
				
			

Now the Device column will display the Name of the related CI.

In addition, grid records can be filtered via select or multiselect

Grids Renderer Tooltip Example

In this example we want to configure the custom rendering of the Title column in a grid of the Service module to display the description of the ticket, when the mouse passes over.

The code you have to insert PHP codethat return a string containing the HTML code that has to be rendered in the grid cell.

We will then use PHP to access the operation fields and to properly build the string containing the HTML code.

To enter the custom renderer configuration code click on the </> icon in the Renderer field to display the scripting area.

And insert the following code:

				
					//print the ticket title
$html = '<div title="_" class="deepTooltip" data-tooltip-content="#deep_tooltip_content_'.$row->getId().'" style="min-width:300px;font-weight:bold;">' . $value . '</div>';
//define tooltip content ticket Description
$html .= '<div style="display:none;"><div id="deep_tooltip_content_'.$row->getId().'">'.$row->getDescription().'</div></div>';
//initialise tooltip js component
$initToolTip = Deep::registry('deep_grid_title_tooltip');
if(!$initToolTip){
    Deep::register('deep_grid_title_tooltip', true);
    $html .= '<script type="text/javascript">
        jQuery(document).ready(function(){
            jQuery(".deepTooltip").tooltipster({
                theme: "tooltipster-shadow",
                interactive: true,
                side: "right"
            });
            jQuery(".deepTooltip").attr("name", "");
        });
    </script>';
}
 
return $html;
				
			

Now, passing with the mouse pointer over the Title column, a tooltip containing the description of the Operation in that row will appear.

Grids Renderer Link Example

In this example we want to configure the Title column, in a grid of the Service module, to contain a link to open the operation in another tab.

To configure this behavior we must insert in the Renderer scripting area of the Title column the following code:

				
					//retrieve the title of the operation
$value = $this->escapeHtml($row->getTitle());
//I define the url to insert in the link
$url = Deep::getUrl("*/service_operation/edit", ["id" => $row->getId()]);
//the string with the html code is returned to generate the link
return "<div style='width: 300px; font-weight: bold'><a href='$url' target='_blank'>$value</a></div>";
				
			

Grids System Configuration

GRID RELOAD INTERVAL

In Deepser there is a system configuration that allows you to define the reload interval of the grids.

You can change the value of this configuration from the System>Configuration>Grids>Configurations section the value is expressed in seconds.

The recommended default value is 300.

Form Template Theory

All Deepser entities have a template form by default.
In particular, this Form Template is the one that is applied if there are no other templates for that entity in the system.

The moment a record is saved to the system with a certain Form Template, it is storicized in the DataBase and is no longer automatically modified by the system. At this point you can only change the Form Template manually.
This behavior, which is the basis of Deepser, is used to provide certainty about the Form Template used and establishes that once you have collected a set of information and saved it in the database, it will be displayed in the same layout as the one used to create the record. Obviously, as we said, there is always the flexibility to modify the layout manually.

The Form Template, instead, varies dynamically when the record is not yet saved in the DataBase.
This behavior allows you to adapt the form fields (and the layout of the record entry screen) according to the characteristics of the data you are entering into the system.
As said before, if you need certain information for a category or for a type of Service Operations, you can configure as many Form Templates as there are layouts that you want to set.

The dynamic modification of the Form is made possible thanks to a set of rules (Form Template Rules) that are inserted during the configuration phase of the Template.
The Form Template Rules in fact play a fundamental role in the configuration of the dynamic change of the templates and must be implemented with great care to create a flexible and powerful system of dynamic forms that adapt themselves according to the data we are inserting in the system.

FormTemplates

All Deepser editing forms are customizable through a graphical configuration editor, you can also apply specific templates to records according to their characteristics.

The goal is to provide Agents and Users with a template containing a minimum set of data, in order to speed up, as much as possible, the opening and handling of requests.

As you can see from the following images the Form Templates can be different in shape and number of fields, to meet specific needs.

FormTemplates Structure and Buttons

FORM STRUCTURE

In Deepser forms are composed of the following components:

  • Tab
  • Fieldset
  • Fields
  • Buttons

TAB

By using tabs you can organize the fields of a form into several different “screens”.

You can navigate between them in the menu on the left (indicated by the green box in the figure).

It is useful to use tabs when the form contains many fields, and would become too long vertically, then you can divide and organize them into different tabs according to their context.

FIELDSET

Fieldsets (set of fields) are the “containers” of the fields of a form.

A single tab can contain multiple fieldsets.

Fieldsets are useful to group fields according to their context; for example it is useful to group the general information of a ticket, or the data concerning the applicant of a ticket, or the system fields concerning the creation and/or the last modification of a ticket.

FIELDS

The fields are simply the fields of an entity (Service Operation, CMDB CI, CRM Contacts etc.) such as Title, Name, Description etc.

The fields of a form are organized in fieldsets.

Some fields may not be editable or may be pre-filled, depending on the configuration made by system administrators.

BUTTONS

The buttons on the forms in Deepser allow you to perform actions that system administrators have decided to make available.

The standard buttons mainly used are the following:

BUTTONSIGNIFIED
ApplySave and submit the current form, but stay on the same page.
SaveSave and submit the current form, but return to the previous page. Example: a Service Operation is saved, and returns to the main grid.
DeletePhysical deletion of an entity, which will be permanently deleted from Deepser.
ResetRoll-Back of changes made to form fields but not yet saved. The entity will be restored with the data updated to the last time the enitity was saved.
BackReturn to the previous page.

Form Template Selection and Creation

TEMPLATE SELECTION

In Deepser for each entity you can have different form-templates.

To manually select a template (as a user with Role Administrator or Agent) just open the Template menu and select it.

TEMPLATE CREATION

To create a new Form Template, from the Form Template menu inside a record (as user with Role Administrator or Agent) you can select the New Form Template item.

At this point Deepser will ask you to specify a name for the new Template.

Once you have entered the name click on the Save button to create the Template.

The new template will be a clone of the template that was “loaded” at the time of creation.

Once saved, the Template will be selectable from the form-template menu.

Form Template Configuration

In Deepser you can change the structure of a form-template quickly, through a simple and intuitive graphical interface.

To access the configuration interface of a form-template click on the “pencil” icon (visible only by users with Role Administrator or Agent) in the upper left area of each Form Template.

EDIT FORMTEMPLATE

The configuration interface contains the configuration data of the Form Template, and the components that define its structure displayed in a tree.

From here you can change the name of the template after its creation.

EDIT RULES

By clicking on the ‘Edit Rules‘ tab you can assign a priority to a template and define the loading rules.

Priorities and Rules define the template to be loaded dynamically when creating a new record. The priority defines the order in which the templates will be tested, in sequence, until one is found whose condition, expressed through the rules, is verified.

In the following example the template is assigned a priority of 150 and the query builder expresses the rule: this template should only be loaded if the Category1 field is ‘Network‘.

Form Template Structure Configuration

Form Templates in Deepser are structured according to a hierarchy of container elements.

On the first level there is the Form, which can contain a set of Tabs, which in turn can contain Fieldsets. Each Fieldset contains a variable number of Fields.

To add new items within the Form Template configuration screen, right-click and add the chosen “sub-element”.

FILDSET AND TAB

When adding new tabs or fieldsets, their position can be simply changed by drag&drop.

Once you have created a Tab or Filedset you can change its name from its configuration screen.

Formtemplates Fieldset Configuration

To access the configuration screen of a fieldset simply select it in the tree structure in the Form Template configuration screen.

You can define the name of the Fieldset and the status.

Inside the Fieldset there are the fields visible inside the Form.

On the right side there are all the available fields, in the center those visible inside the selected Fieldset.

You can show a field in a Fieldset by simply drag and drop it from the Available Fields to the Fieldset.

To delete a field from a Fieldset simply drag&drop it from the Fieldset to the Available Fields area on the right. At that point, the Field will be available to be inserted in other Fieldsets.

Note: fields cannot be replicated on the various Fieldsets, so if the field is inserted in a specific Fieldset it cannot be replicated also in another Fieldset (for example) in another Tab.

Formtemplates Buttons Configuration

From the Form Template component tree you can also manage the buttons.

By right-clicking on a button you can delete it.

Simply selecting it, instead, you can act on its configuration.

The fields have the following meaning

FIELDSIGNIFIED
LabelText in the button.
CodeAdditional identification. Used for system buttons only.
AreaForm Area where the button has to be displayed (Header or Footer).
StatusIf Disabled the button will not be added to the form.
ClassWith this field you can assign one or more css classes to the button.
OnClickScripting area where you can define the OnClick action of the button.

Formtemplates Field Configuration

Form fields are editable within Fieldsets.

To change the appearance and configuration of the individual Field, click on the “gear” icon in the Field.

The Field management popup appears at this point:

The configuration fields of the Field have the following meaning:

FIELD DESCRIPTION
Default Value Default value of the field. This value is defined at the Form Template level. Note: For Select type fields you must specify the key of the option to pre-select it.
Disabled Indicates whether the field is active or not. A disabled field will not be part of the form submitted for saving.
Readonly Indicates whether the field is read-only
Required Indicates if the field is mandatory. If mandatory, the form cannot be saved until the field has a value.
Reload Form This field is important for the application of the Form Template Rules. If it is set to “Yes“, it means that when you edit the field, the form is reloaded and any Form Template Rules are applied.
Columns Indicates the size of the field. The field can have a maximum size of 6 and minimum size of 1. A field that occupies 6 columns, graphically speaking, will occupy the entire line of the form.
Margin Left Indicates the left margin of the field. Note: The sum of the value set in the Columns field and the left margin will always be less than or equal to 6
Line break Indicates if other fields can be rendered on the same line.
Hidden Indicates if the field is hidden.
Readonly for groups By this field, you can define the field will be seen as Readonly form members of some groups.
View only by groups By this field, you can define the field will be seen only by the members of some groups.

Advanced Form Template Rules

In Deepser you can define the rules for loading Form Templates via PHP script.

It is useful to be able to define conditions “manually” by scripts when they are too complex or particular to be expressed by query-builder.

To define a rule by scripting, go to the configuration menu of the Form Template, move to the tab (on top) Edit Rules and click the icon </> above the query-builder  (as shown in the picture).

In this area you will find the code automatically generated by query-builder that you can integrate or replace with custom PHP code.

EXAMPLE: TEMPLATE FOR IT SECOND LEVEL MEMBERS

In the following example we want to make a template visible only to users who are members of a specific group: IT Second Level.

To do this you need to enter the following PHP code in the Rules scripting area.

				
					//retrieve the current user
$currentUser = Deep::helper('deep_admin')->getCurrentUser();
//IT Second Level group id = 5
//check if the user is in IT Second Level group
if($currentUser->isInGroup(5)){
    //original condition generated by the query-bulder
    if( $this->getModel()->getData('type_id')==1 &&
            ( $this->getModel()->getData('category1')==5 ||
                $this->getModel()->getData('category1')==17 ||
                $this->getModel()->getData('category1')==2 )){
        //if both conditions are verified the template form is loaded
        return true;
    }
}
else{
    //else return false and evaluate the rules of the next template
    return false;
}
				
			

Custom Button Configuration

You can define, within a Form Template, several custom buttons to perform custom actions.

DEFINITION OF CUSTOM ONCLICK ACTIONS

To access the script area to define OnClick custom, from the configuration screen of a button, click on the icon </> next to the OnClick label

At this point you will open the scripting area, where through PHP code, you can build the string containing the JavaScript code that will implement the action desiserata.

EXAMPLE 1: SEARCHING FOR THE TITLE OF AN OPERATION ON GOOGLE

In the following example we want to implement an OnClick action that searches on google the title of an operation and displays the search results in a new tab.

				
					#retrieve from the current site (ticket) its title
$operationTitle = Deep::registry('current_model_instance')->getTitle();
#build the url to search on google
$url = "http://www.google.com/search?q=".urlencode($operationTitle);
#return the onlclick code of the HTML element
return "window.open('$url')";
				
			

EXAMPLE 2: CLOSING AN OPERATION AND SENDING REPORTS

In the following example we want to implement an OnClick action that puts an operation in a closed state, and gives the user the possibility to send the report to the applicant, through the email event already configured.

				
					// confirmation prompt message
$msg = $this->__("Sent report?");
// $js is a string that contains JavaScript code
$js = <<<JS
//status field is set to Closed
jQuery('#operation_status').val(3);
//confirmation prompt element configuration
jQuery.confirm({
    title: null,
    content: '{$msg}',
    containerFluid: true,
    closeIcon: true,
    buttons: {
        save: {
            text: 'OK',
            btnClass: 'btn-blue',
            action: function(){
                //if user press OK trigger the send report email event
                jQuery('#operation_cust_sendreport').val(1);
                //save current operation
                saveAndContinueEdit();
                return true;
            }
        },
        cancel: {
            text: 'NO',
            action: function () {
                saveAndContinueEdit();
                return true;
            }
        }
    },
});
//end of JavaScript string
JS;
//return JavaScript code
return $js;
				
			

Buttons Conditional Hiding

It is common to show a button only when certain conditions are verified.

To do this you need to assign a CSS class (the name it’s your own choice) to the button.

The CSS class will provide an easy way to select via jQuery the button and then disable it.

The code to hide a button must be executed when the formi s loaded, so we must use the Script area in the Form Template configuration menù.

EXAMPLE 1: HIDE OPERATION BUTTON IF IT IS ALREADY IN THE CLOSED STATE

In the following example you want to hide the Close Operation and Send Report button (Example 2 section OnClick Custom) if the ticket is already in a closed state.

Step 1: We assign a CSS class to the button from the button configuration screen.

Step 2: Go to the Form Template configuration screen, expand the Scripting Script area by clicking on the </> icon.

And insert the following code:

				
					// $js is a string that contains JavaScript code
$js = "";
// if status is closed
if (Deep::registry('current_model_instance')->getStatus() == 3)
    //add to JavaScript string the jQuery code tu hide the button
    //note the css class defined in step1 is used in selection
    $js .= "jQuery('.btn-close').hide();";
//return JavaScript code
return $js;
				
			

User Portal

The Deepser user portal, is the frontend interface presented to end users, and if properly configured, it allows to easily create and consult tickets, get access to CMDB, CRM, Knowledge base and password manager.

The user portal is displayed after logging in into the deepser frontend.

Note: The domain select above the ‘User Name’ field is used to choose which domain controller to use to log in, if configured.

If the login was successful, the User Portal will show.a

Browsing the user portal

The Deepser user portal is made out several areas, the most important section of the page is functional to the creation and management of tickets, while the drop-down menu allows you to access the other features.

The meaning of the various sections is here described

FunctionSectionDescription
Help Desk(Ticketing)Service GroupIndicates the group to which a certain type of service belongs. For example, requesting a new device is part of the IT Support group.
Service RequestService RequestIndicates the type of ticket that will be created. For example, the request for a new device is part of the ‘Requests’ type.
Service OperationsService OperationsShows All tickets that are configured to be visible to the current user. There may be multiple grids to make it easier to view, for istance , the grid displaying  open tickets, the grid displaying tickets being processed and the grid displaying closed tickets.
CMDB, Knowledge Base, Password ManagerDropdownAppears by clicking on the arrow to the right of the user, allows you to navigate through the other modules configured as visible in the user portal.

Managing Tickets in The User Portal

The first function of the user portal is to allow Deepser end users to create and manage tickets.

1 – First of all login with your credentials to the user portal through the login screen

2 -Then select the interested group, and the type of ticket you want to create (in the example you want to create a request from the IT Support group).

3 – At this point, the ticket creation form will open, this must be be filled in with the interested values (in the example we ask for a new laptop), once filled in click on Apply.

3a – The meaning of the fields is as follows

FieldDescription
CategoryThe category and the consequent subcategories of the ticket.
TitleThe title of the Ticket
UrgencyThe urgency is the ticket
Knowledge BaseField dynamically populated with all the articles that match the ticket title in terms of tags.
DescriptionTicket description

4 – By default, the created ticket will appear under the Open Requests grid, clicking on it you can see the details.

5 – Once opened, you can follow updates on ticket resolution, add attachments, comments, etc.

User Portal Additional Features

In addition to ticket management, the user portal also allows access to the CMDB, CRM, Knowledge Base and Password Manager, all through the drop-down menu, which can be activated by clicking on the arrow to the right of the current user.

This is the complete menu of all the items related to the various modules configured in Deepser.

ItemDescription
CMDBContains all visible entries in the Configuration Management Database module.
CRMIt contains all the contacts, companies and visible opportunities of the Customer Relationship Management module.
Knowledge baseIt contains all the support articles, internal guides, etc. of the Knowledge base.
PasswordIt contains all visible passwords of the password manager module.

Note: Each functionality is simply introduced, to have a detailed guide, refer to the respective articles of the Academy.

Configuring Portal Groups

SERVICE OPERATION CONFIGURATION OVERVIEW

In order to correctly display help desk services on the portal, the Portal Groups, Portal Request and Portal Operations must be configured correctly.

The following guide aims to create a new service Group Training, in which it will be possible to make training requests, and then make it visible in a customized grid.

The meaning of the areas is the following:

SectionDescription
Service GroupIndicates the group to which a certain type of service belongs in the portal. For example, requesting a new device is part of the IT Support group.
Service RequestIndicates the type of ticket that will be created. For example, the request for a new device is part of the ‘Requests’ type.
Service OperationsShow All tickets that are configured to be visible to the current user. There may be multiple grids to simplify the view, for example, the grid for open tickets, the grid for tickets being processed and the grid for closed tickets.

1 – Access to the item ‘Portal Group’ from the Backend of Deepser, through Sistem ->Portal->Group

2 – Add anew group on the portal by clicking the Add a portal Group button.

3 – Enter a name, the position where it will appear among the portal groups, visibility in the portal and status, as active. Finally save the new group.

Note: Portal Requests does not show any value because portal requests still must be configured. Moreover, if not visible, the field Portal Visibility, must be dragged inside the template form through the pencil-shaped edit button on the top left (to learn more about the topic visit the appropriate section of the academy).

Configuring Portal Requests

1 – To configure a new request, and make it part of a group, go to System->Portal->Request.

2 – Add a new request on the portal by clicking the Add portal Request button.

3 – Fill in the Request creation form, and then click on Save.

The meaning of the fields is as follows

FieldDescription
NameRepresents the name of the Portal Request.
TypeIt indicates the service type of the ticket that will be generated by this portal Request.
TemplateIndicates the Form template used when creating the request. It is advisable to create two templates, one for the creation, and a NO EDIT one to view the tickets created (for more information visit the dedicated section of the academy).
IconAllows you to choose an icon to be displayed in the portal next to the request.
Portal GroupsIndicates the group to which this Portal Request will belong.
DescriptionIndicates the description that will be shown under the request, this is useful to make clear to end users the purpose of this portal request.
UrlIt allows to transform the portal request to a link. So, if set, when you click on the request in the portal, it will not open a ticket, but the link.
StatusIndicates the status of the request portal(Enabled/Disabled )
Frontend VisibilityIf set to yes, it will make the request visible in the Guest Portal.

3a – After saving, the request will appear as visible within the group.

3b – In addition, the request will also be visible in the Users portal.

Configuring Service Operations in the User Portal

Deepser user portal allows immediate access to the tickets of which you have visibility, through the Service Operation grids, present in the lower part of the portal.

By default, there are 3 grids, Open Tickets, Loaded Tickets and Closed Tickets, and they show the tickets that the current user is requesting.

These grids are totally customizable, so they can show a collection of tickets, filtered according to the rules set.

This guide will show you how to create a custom ‘Ticket with High Urgency’ grid.

1 – Open the portal grid configuration, through System->Portal->Operation.

2 – This menu allows you to view and modify the grids in the user portal. Click on New to add a new grid.

3 – Enter a name, then click on Save.

4 – Enter the grid editing mode by clicking on the pencil button.

5 – Configure the grid to show the needed fields, with the required filters of the query builder, and selecting the groups that will have visibility (in this example a grid has been configured that displays all urgent tickets in open state). Finally click on Save.

Note: For more information on how grid editing works, see the appropriate section of the Academy.

6 – After following all the steps, a new grid will appear in the user portal showing tickets that meet the conditions set.

Enabling Other Modules in the User Portal

Through the user portal, it is possible to give end users access to CMDB, CRM, Knowledge Base and Password Manager modules. To make this possible, you need to Enable them

0 – First go to Deepser System configuration, going to System->Configuration->Portal->Configuration.

From here you can set the visibility of each module in the portal

ENABLING THE PASSWORD MANAGER IN THE USER PORTAL.

To enable the password manager, select Password, set Enabled to Yes, select the list of groups that will have access to the module in the user portal, and finally click Save Configuration.

ENABLE THE KNOWLEDGE BASE IN THE USER PORTAL.

To enable the password manager, select the Knowledge Base item, set Enabled to Yes, select the list of groups that will have access to the module in the user portal, and finally click Save Configuration.

Note: To be actually visible on the portal, both articles (accessible from the KB edit) and sections (System->Knowledge Base) must have Portal Visibility set to Yes.

For a detailed guide, please refer to the Academy’s topic.

ENABLE THE CRM MODULE IN THE USER PORTAL.

To enable the password manager, select the CRM item, for each type of item, set Enabled to Yes and select the list of groups that will have access to the module in the user portal, finally click on Save Configuration.

ENABLE THE CMDB MODULE IN THE USER PORTAL.

To enable the CMDB, select the CMDB item, set Enabled to Yes, the Enable Priority parameter allows you to decide whether to follow the value of the CMDB Portal Visibility item set for each user, or to enable it for all users, and finally click on Save Configuration.

ENABLE WORKLOGS IN THE USER PORTAL.

To show the activities to end users in the user portal, select the Activity item, set Show Worklogs to Yes, to allow end users to add and edit them, set Add/Edit Worklogs to Yes, and finally click Save Configuration.

Enabling Other Modules in the User Portal Grid

The CMDB, CRM and Password Manager modules, have editable grids in the user portal, this allows you to filter the display of each element, or organize them differently.

The following guide gives a brief view about the topic of editing grids, to learn more, go to the specific section of the Academy.

CHANGE THE PASSWORD MANAGER GRIDS IN THE USER PORTAL.

To change the password manager grid in the user portal, navigate to System->Portal->Password .

It will then open the grid displayed by default in the Users portal, to modify it click on the pencil icon, instead to create a new one, click on the new button.

MODIFY THE CRM GRIDS IN THE USER PORTAL.

To modify the CRM grid in the user portal, navigate to System->Portal->CRM, and select the type of element concerned (Account, Contact or Opportunity), the procedure applies to all three.

It will then open the grid displayed by default in the Users portal, to modify it click on the pencil icon, instead to create a new one, click on the new button.

MODIFY THE CMDB GRIDS IN THE USER PORTAL.

To modify the CMDB grid in the user portal, navigate to System->Portal->CI , and select the type of element concerned (Account, Contact or Opportunity), the procedure applies to all three.

It will then open the grid displayed by default in the Users portal, to modify it click on the pencil icon, instead to create a new one, click on the new button.

Guest Portal

The Guest Portal also allows users not registered in Deepser to access the system and take advantage of certain features such as opening Tickets or looking into the Knowledge Base.

In order to allow non-authenticated users to use these resources, they must be properly configured.

Enabling the Guest Portal

The guest portal is not enabled by default, to enable it go to the System > Configuration > Web > Default Pages section, enable the Enable Frontend option , and click on the Save Config button .

At this point the Guest Portal that will be loaded is the one already present in Deepser with its default configuration.

From the Guest Portal it will then be possible to return to the area dedicated to authenticated users by selecting the Login item from the menu (top right) .

Note: Once the Guest Portal is enabled, the new Home Page will be the latter, no longer the login screen.

LOGO MODIFICATION

The guest portal is fully configurable, by default neither ticket creation nor access to knowledge base articles is enabled.

To replace the Deepser logo in the Guest Portal home, go to System > Configuration > Design > HTML Head and load the new logo under Frontend Logo.

Guest Portal Visibility Configuration Overview

VISIBILITY CONFIGURATION OVERVIEW

On the Homepage, once enabled, the Guest Portal is present. In order to allow, through the latter, the opening of new Tickets, it is necessary to properly configure the Service components, and then enable them to be used in the Guest Portal: Service Types, Portal Group and Portal Request.

Enabling Service Types on the Guest Portal

To enable the creation of Service Operations from the Guest Portal, at least one Service Type must be enabled in the Guest Portal. Only Operations of the enabled types can be created.

1 – To enable a type go to the System > Service Configuration > Typologies section and after clicking on the desired type set the Frontend Visibility field to ‘YES’.

1b – If the Frontend Visibility field is not present, it must be added to the form.

To do this, enter the edit mode of the form by clicking on the pencil icon in the top left corner

1c – Finally, select the Form Type, via drag&drop, drag the Frontend Visibility field into the form and press Save, then refresh the page.

Adding a Portal Group in the Guest Portal

To enable the creation of Service Operations from the Guest Portal, it is necessary to enable at least one Portal Group to be visible in the Guest Portal.

To enable a Portal Group go to the System > Portal > Group section and after having clicked on the desired group set the Frontend Visibility field to ‘YES’.

Please Note: If the Frontend Visibility field is not present, it is necessary to add it to the form. To do this, enter the form editing mode (clicking on the pencil icon in the top left corner) and, using drag&drop, drag it into the form, then refresh the page so that the field is displayed.

Note: a Portal Group will be displayed in the Guest Portal only if it contains at least one Portal Request configured as visible (in the Guest Portal) and this is of a type configured as enabled (for the Guest Portal).

Adding a Portal Request in the Guest Portal

As for the portal dedicated to Endusers, Service Operations (Tickets) are created by Guest users through the configured Portal Requests.

1 – To enable a Portal Request go to the System > Portal > Request section and after clicking on the desired request set the Frontend Visibility field to ‘YES’.

Please Note: If the Frontend Visibility field is not present you need to add it to the form. To do this, enter the form edit mode (by clicking on the pencil icon in the top left corner) and, using drag&drop, drag it into the form, then refresh the page so that the field is displayed.

2 – If the Template field is valorized, remove the value by pressing the ‘x’ to the right.

Please Note: At this point, the loading of the formtemplate will respect the rules

3 – Now the user portal will show the requests of the configured type and group.

Editing Form Templates in the Guest Portal

Once the requests are made visible in the guest portal, they will have all the ticket fields filled in, which makes it necessary to edit the form template.

1 – Access the guest portal through an Admin user, to do this you need to remove all the right side of the url. (E.g. test.deepser.com/admin/system_account will become test.deepser.com)

 

2 – Select a request

3 – All fields can be set by default by the guest user, to modify the available fields, open the form editor.

4 – Once you have selected the correct fieldset, modify it as needed, keeping in mind that this form will be accessible to guest users.

Note: When a guest user opens a ticket, they will be recognizable by their email, so in this case the Requester Email field should be added as mandatory.

Enabling Categories in the Guest Portal

To make a Category visible in the Guest Portal you need to go to the System > Categories section of the Deepser backend.

1 – Once the desired category has been selected in the “Category” tab, set the Frontend VIsbility field to “YES”.

2 – If ad-hoc rules are defined for some models move to the “Models Visibility” tab and change within the rules the value of the Frontend VIsbility field.

Enabling Notifications for Guest Users

An Email Event ” REQUESTER USER – Operation Opened by Frontend User ” has been set up in Deepser to notify the “guest” user that the ticket has been created.

1 – By default the event is disabled, to enable it go to the System à Tools à Email à Event section .

2 – The related email template is configured to send via email the link that allows you to consult the ticket even to an unregistered user.

In Deepser it is possible to create custom email events, if necessary it will therefore be possible to define new events such as the notification of inserting a comment or the closing of the ticket.

Knowledge Base in the Guest Portal

The Guest Portal includes a section containing Knowledge Bases that have been configured to be made public and available even to users not registered in Deepser.

Note: Knowledge bases published in the Guest Portal are indexed by search engines.

CONFIGURATION KNOWLEDGE BASE – HELP

1 – To make a Knowledge Base visible in the Guest Portal you need to go to the SystemàKnowledge Base section of the Deepser backend and click on the KB that you want to make visible in the Guest Portal. In the Form of the KB configure properly the following fields:

  • Frontend Visibility: Set to ‘YES’ to make the Knowledge Base visible in the Guest Portal.
  • Identifier: This is the name of the resource (in this case the Knowledge Base) that will appear in the URL.

If not set it is automatically calculated when the form is saved.

1b – At this point, the article page will present as the last part of the URL the string previously chosen as identifier.

2 – To then make visible an Article of a Knowledge Base just made visible in the Guest Portal you need to go to the Knowledge Base section of the Deepser backend and click on the KB containing the article you want to make visible in the Guest Portal.

Choose the article and in its Edit form properly configure the following fields:

Frontend Visibility: Set to ‘YES’ to make the item visible in the Guest Portal.

Identifier: It’s the name of the resource (in this case the article of a Knowledge Base) that will appear in the URL. If not set it is automatically calculated when the form is saved.

2b – In the same way of Knowledge Base, also the article will present as last part of the URL the string previously chosen as identifier.

CMS in the Guest Portal

You can change the look and feel and manage the content of the Guest Portal via Deepser’s built-in CMS.

To access the CMS go to the System > Tools > CMS section of the Deepser backend.

PAGES

Through CMS it is possible to define the pages that will belong to the Guest Portal. In its default configuration, Homepage and 404 Not Found are already defined, which are sufficient for an essential configuration.

The tabs that contain the main configurations of a page are Page Information and Design.

To change the configuration of existing pages or create new ones go to the SystemàToolsàCMSàPages section of the Deepser backend.

PAGE INFORMATION

The fields within the Page Information tab have the following meaning:

  • Page Title: page title
  • URL Key: name of the page to be used in the URL
  • Status: status (Active/Inactive)

DESIGN

In the design tab you can choose the page layout from those proposed.

In the Layout Update XML scripting area you can add blocks to the page structure.

STATIC BLOCKS

You can also create new static blocks, or modify existing ones, which will be “injected” into the CMS pages.

To change the configuration of existing blocks or create new ones go to SystemàToolsàCMSàStatic Blocks section of Deepser backend.

The Block Configuration Fields have the following meaning:

  • Block Title: Block Title.
  • Identifier: Block code.
  • Status: Status (Active/Inactive).
  • Content: Area of scripting through which to define the structure of the block.

Cache Management

To increase the performance of the Deepser application, a level of caching was introduced that allows you to obtain the Deepser pages, as well as the CSS or, in general, the content provided by Deepser from a static copy, thus avoiding the need to regenerate them every time a user opens the page.

On some occasions, however, it may be necessary to delete this cached copy to make changes that would otherwise only be visible after the cache has expired. For example, after adding a custom configuration or changing some labels in Deepser.

Delete the cache in Deepser

To delete the cache in Deepser you will need to go to the menu:  System -> Cache Management.

At this point the following screen will open:

Cache Storage Management

This section contains all cache types available in Deepser, which you can enable/disable or refresh.

This can be done with the following available buttons in the top right corner of the form:

Name

Description

Notes

Flush Cache

This button when pressed deletes the cache of Deepser pages.

 

Flush Cache Storage

This button when pressed deletes the cache of both pages and contents of Deepser, so everything will be reloaded.

This button when pressed will ask for a confirmation by opening a popup where you will need to click on “OK” to proceed.

Action / Submit

This command allows you to perform one of the following actions on the modules listed below:

– Refresh (reload the lock cache),

– Enable (enable the lock cache),

– Disable (disable the lock cache).

 

 

Cache Type Explanation

In this section, the complete list of available cache types and their meaning:

Name

Description

Configuration

This module is the cache of Deepser configuration files.

Layouts

This module is the deepser Layout file cache.

Blocks HTML output

This module is the cache of html blocks generated by Deepser.

Translations

This module is the cache of translations in Deepser.

Collections Data

This module is the cache of Deepser collection files.

Web Services Configuration

This module is the cache of the deepser web service configurations.

User collection Data

This module is the cache of user data collections in Deepser.

Device collection Data

This module is the cache of device collections in Deepser.

Additional Cache Management

From this section you can act on CSS/JS cache in Deepser.

Button

Description

Flush JavaScript/CSS Cache

Delete the cache of CSS files and JavaScript files used in the Deepser theme.

Websocket Server Assets

From this section you can act on websocket server for the assets in Deepser.

Button

Description

Check Server Status

This button when pressed allows you to check the status of the Websocket server that distributes the assets in Deepser

Stop Server

This button when pressed allows you to disable the Websocket Server that distributes the Assets in Deepser.

Reboot Server

This button when pressed allows you to reactivate the Websocket Server that distributes the Assets in Deepser.

Chat Websocket Server

From this section you can act on chat websocket server in Deepser.

Button

Description

Check Server Status

This button when pressed allows you to check the status of the Websocket server that manages the chat in Deepser

Stop Server

This button when pressed allows you to disable the Websocket Server that manages the chat in Deepser.

Reboot Server

This button when pressed allows you to reactivate the Websocket Server that manages the chat.

Flow Contexts

From this section you can act on flow context log in Deepser.

Button

Description

Delete Context Log File

This button when pressed allows you to delete the flow log files, the flow log files allow you to see the progress of the flows (only if the flows are enabled)

System Information

From this section, you can view system information for the current server. The information you can check includes the following:

Name

Description

Notes

Deepser Version

Shows the version in which Deepser is running

The moment this document was made the version was 2.4.7.12-7

Disk Space

This indicates disk space usage on the /dev/vda1 partition. The used space out of the total space and the used percentage.

This includes not only the space used by the files but the space taken from the database as well.

CPU/RAM

This indicates the percentage of CPU resources currently in use as well as the used RAM out of the total RAM including the usage percentage

 

Quick Reply

Inside Deepser it is possible to configure various automatic quick replies that can be used to set a predefined text into text-area fields, like comment, email body message and solution description . For example it can be used for a default mail response or for a default reply in a ticket. 

Quick Replies Configuration

Automatic quick replies can be configured by an administrator within various Deepser entities.

To configure automatic quick replies, you can navigate to System-> Quickreply-> Reply and the following screen will appear:

In this example, two different quick replies have been configured, one for the Operation model and one for the Activity model.

To add a new quick reply, just click on the “Add Reply” button at the top right and the following screen will appear:

Below is the list of available fields and their meaning:

Field

Description

Note

Name

The name of the quick reply

In the example, it is called “Example Solution”

Type

The type of quick reply

In the example the type is “Default”

Model

The model inside Deepser where you want to insert the quick reply you are creating

Examples

• If you want to insert the quick reply in the ticket comment, the model is “DeepActivity-Activity”

• If you want to insert the quick response in the ticket solution, the model is “DeepService-Operation”

• If you want to insert the quick reply in the email message, the template is “DeepEmail-Message”

Expression

A query builder that allows you to filter by fields of the chosen model

Examples

• If you want to insert the quick reply in the ticket comment, inside the query builder you will have to filter by Model equal “DeepService-Operation”

Expression (Script)

Section where you can insert filters using custom code

 

Status

The status of the quick reply

You can only use enabled quick replies 

Description

Personalized quick reply message

Note: the code inside the curly brackets is used to retrieve the name of the requester user of the ticket

Quick Reply Use

In order to set automatic and customized reply inside a text-area field, like comment, email body message and solution description of a ticket, you can navigate to the desired field (in our example we are on the “Solution” field into the Operation module, reachable from “Closing Info” Tab).

The following screen will open:

To set a quick reply in the field quickly, you can simply navigate to the “Solution” field and click on “Replies”. From there, you can choose a default reply that has been previously configured (in our example, we only have one configured quick reply in the Operation module, with the type “Default” named “Example Solution”).

Once a quick reply is selected, the field will be automatically filled with the default text configured earlier

You can also customize the automatically inserted text according to your needs.

With a proper configuration, it is possible to insert a quick reply also in a comment on a ticket or within the body of an email.

Mentions

The Mentions functionality in Deepser is accessible to all user types. By default, it is enabled for administrators, agents, and key users, but it remains disabled for end users.

The mentions functionality allows users to tag or reference specific individuals within tickets, comments, or other communication threads. This means you can directly notify someone by using “@” followed by their username, ensuring they see and respond to the issue quickly. This feature improves communication by making sure the right people are informed and can take action promptly. It helps teams work together more effectively, keeps everyone on the same page, and speeds up the problem-solving process. In busy environments where many tasks are being handled at once, mentions help keep everything organized and ensure that no important updates or responsibilities are missed.

Once you have mentioned a user they will be notified via email.

Enable the mentions for End-Users

To enable it you need to go to System->Custom Fields.

Here, you need to go to the module it should be enabled for. Then head inside the description field and go to the Extra Tab. Here you can enable or disable the mentions from the field Mentions (for End Users)

Example  – Comments, Activity Module

 If mentions are needed to be enabled for the comments you need to head to the Activity module.

After opening the module, you need to go to the fields tab and then open the description field configurations.

Go to the Extra Tab and here you can enable or disable the mentions from the field Mentions (for End Users).

Module Creator - Creating a custom module

The “Module Creator” is a component of Deepser designed to allow administrative users to create new custom modules intuitively and through a graphical interface, respecting the Deepser data structure.

Accessing the Module Creator

To access the “Module Creator” you need to go to the menu: System > Module Creator.

Once done, the screen below will open:

Creation

To proceed with the creation, it will then be necessary to click on the “Create new module” button at the top right. The screen that will then appear will be as follows:

General Settings Fields List

Below is a list of the fields in the “General Settings” tab and their meanings:

Field

Description

Module name

Name of the new custom module you want to create.

 

NOTE: It can only contain letters or numbers, but no other characters (no spaces allowed).

Admin menu title

This field indicates the name of the module in the left-hand menu

Icon Class

Through this field it is possible to associate an icon to the new custom module which will then always be displayed in the main menu.

As a result, this field refers to the section that is accessible to all users of the backend.

Icon Color

This field allows you to select the color to be applied to the icon and label displayed on the menu.

As a result, this field refers to the section that is accessible to all users of the backend.

Admin parent menu ID

Through this field it will be possible to decide the exact point in the menu where the operational references of the new module will be displayed.

As a result, this field refers to the section of the new form that is accessible to all users of the backend.

 

The selection within the menu must be made by clicking on the note of the “Select menu parent and position” field.

Admin menu sort order

This read-only field, will be automatically populated based on the selection made through the “Admin parent menu ID” field.

Configuration Icon Class

Field used to associate an icon with the configuration section of the newly created custom form. As a result, this field refers to the section accessible to Deepser admin users.

Configuration Icon Color

Through this field it is possible to select the color to be applied to the icon and the configuration label of the new custom module displayed on the menu.

As a result, this field refers to the section accessible to Deepser admin users.

Configuration Admin parent menu ID

Using this field it will be possible to decide the exact point in the menu where to display the references to the configuration section of the new module.

As a result, this field refers to the section accessible to Deepser admin users.

 

The selection within the menu must be made by clicking on the note of the “Select menu parent and position” field.

Normally, the configuration section is located in the System menu.

Configuration Admin menu sort order

This read-only  field, will be automatically populated based on the selection made through the “Configuration Admin parent menu ID” field.

Module Creator – Selecting the Location in the Menu

To proceed with the selection of the position of the new module within the menu, it is necessary to click on “Select menu parent and position” and then on “Insert here” in the selection popup. Here’s an example:

In the example above, according to the screenshot, the new module would be inserted between the “Service” and “IT Asset” sections of the menu.

Saving the module

Once you have finished filling in the fields of the “General Settings” tab, you need to navigate to the “Entities” tab because to proceed with saving, it is necessary for the new form to have at least one entity associated with it. To accomplish this, simply click on the “Add entity” button located at the top right corner. Each new entity is divided into “Settings” and “Fields/Attributes:

Settings

Through the “Settings” section, it will be possible to enable modules for some of Deepser’s standard management tasks, such as the ability to associate categories, configure types, and more.

To proceed to fully view all the fields in the “Settings” or “Fields / Attribute” section, click on the “+” icon next to them. Below is the screenshot of all the configurable fields for the “Settings” section:

Settings Fields

Below is a list of the fields in the “Settings” section and their meanings:

Field

Description

Label singular

Label of the new custom module in singular form.

Label plural

Label of the new custom module in plural form.

Entity code singular

The value entered in this field (which should refer to the name of the new module) will be used for the names of variables, files, and tables within Deepser. This approach simplifies the process of making configurations via the scripting area if necessary. Keep in mind that in this field, the value should be specified in singular form.

Entity code plural

It serves the same purpose as the “Entity code singular” field, except that in this case you need to specify the value in plural form.

Manage Advanced Permissions with Groups and Companies

If you set this value to YES, the “Owner Group”, “Owner Company”, and “Owner User” fields will be created. Through these fields it will be possible to manage the entity of the new module through custom group rules.

Manage Advanced Accesses

Setting this field to YES will create the “Access Group”, “Access Companies”, and “Access Users” fields that are typically used to “expand” visibility for the records.

Associate Categories

Setting this field to YES will create the fields “category1”, “category2”, “category3”, “category4”, and you will then be able to associate the standard Deepser categories with the entity of this new module as well.

Add Type Entity

By setting this field to YES, the “Type” field will be created and you will then be able to manage the types on this entity of the new module.

Manage History Changes

Setting this field to YES will create the “History Changes” field for this new form. Through this field it will be possible to have the history of all the changes made on a record of that entity.

Visible on Portal

By setting this field to YES, it will be possible to manage the new entity also on the end customer portal side.

Add Routing

By setting this field to YES, you will also be able to use the new entity in Deepser routing rules.

Use Icon

Setting this field to YES will create an “icon” selection field, enabling you to associate an icon to the new entity.

Icon Class

This field allows you to select an icon to display in the menu for this new entity.

Icon Color

Field linked to the previous “Icon Class” that allows you to select a color for the icon and label of the entity.

Fields/Attributes

Once you have finished filling in the “Settings” section, you will need to consider creating new dedicated fields for the new entity. To access the details of the “Fields / Attribute” section, you will need to click on the “+” icon. From here, you can add new fields to the entity. To do this, simply click on the “Add field / attribute” button. Here’s the screenshot:

Fields/Attributes List

Below is the list of configurable fields for a new field/attribute:

Field

Description

Attribute code

This field indicates the field code that will be used for tables and variables in Deepser. Therefore, it is necessary to adhere to some guidelines:

– The first character must be a letter

– Only lowercase letters, numbers, or underscores (_) can be entered

– Reserved names such as “data” or “child” cannot be used.

Attribute label

This field indicates the label of the field that will be displayed in the forms.

Attribute Type

Through this field you can indicate the type of field you want to create.

Acts as name

Each entity must have an attribute to function as its “Name”. This attribute will be used to distinguish between different entities and will also appear in dropdown menus with entities. This option is only available for text, numeric, and decimal attributes.

 

NOTE: Only one of the defined fields can have this flag. Normally you should use it for the main field of the entity you’re creating.

Required

If set to Yes, it indicates a required field.

Use WYSIWYG editor

If set to Yes, it indicates that the field can be managed by editor.

The field is activated only if the type of field created is “Textarea”.

Show in admin grid

When set to Yes, includes the new field in the entity’s default grid.

Options in select

Useful field to indicate a list of values for select or multiselect fields. All values entered in this field must be separated by a pipe (|) delimiter. If you want to include an empty option as the first value, you must start with a pipe symbol.

Saving the fields/attributes

Once you have completed all the main configurations and entered all the fields of your interest, you can proceed with saving the new custom module. You can then proceed by clicking on “Save” or “Save and Continue Edit”.

Installing the module

Once saved, it will then be possible to install the new module using the dedicated “Install” button:

Once the installation is complete, you will find the new module and its entity in the Deepser menu.

Regenerate Button

Within the configuration of the new custom module, a new “Regenerate” button will appear:

The button in question will be used to regenerate the module if its configuration is changed. For example, if a feature is enabled on one of its entities or if a new field is simply added, clicking on the “Regenerate” button will allow you to propagate and apply the changes.

The button will proceed to make a backup of the data entered so far in the custom module, to delete and recreate the structure of the module and finally to restore the data previously entered.

Uninstall Button

After installation, in addition to the regenerate button, the “Uninstall” button will also appear. By clicking on that button, the entire configuration of the custom module and the custom module itself (including the records saved within it) will be permanently deleted. You will then not be able to recover the data.

Import/Export

Through “Module Creator”, it is also possible to export and import the entire configuration of a created module.

In fact, once the module configuration has been saved, returning to the main list of custom module management (again from the > Module Creator System), an “Export” column will be available on each individual configuration record and an “import” button through which it will be possible to export and import the configuration of a module.

Below is an explanatory screenshot:

SSO Login/Provisioning Configuration – Azure

In Deepser you can set up SSO using Azure as the default provider.

This article explains how to configure Deepser and Azure, to allow SSO and User Provisioning via Azure Account in Deepser.

It includes 3 steps:

  • Oauth client creation in Deepser: In this step we can obtain a Redirect Uri for using it in the next step (Azure Configuration).
  • Azure configuration: The configuration from provider side.
  • Oauth client configuration completion in Deepser: The completion of the Oauth client created in the first step.

Note: SSO Login can be configured only on HTTPS protocol.

Deepser Oauth Client Creation

To configure a new SSO integration you will need to go to the System >Tools >OAuth >Client menu

Here you will need to click on the “Add Client” button:

As a first step you will need to assign a name to the client and click and set the following fields as follow:

Name is the name of the oauth client.
Provider you should select Azure and type as User. The Tenant ID will be populated after you finish.

Then you can click on “Apply” or “Save” button.

After the saving you can be able to copy the “Redirect URI” from the following field:

The “Redirect Uri” will be needed to configure the provider->side SSO (Azure in our case).

So, the first step of Azure SSO Configuration in Deepser is concluded. The next steps will be Azure Configuration and then the completion of the configuration in Deepser.

Azure Configuration

In this step we can manage the configuration from provider side (Azure).

You will need to login as administrator to the Azure portal: https://portal.azure.com/.

Note: We recommend performing all configurations in incognito mode or in a browser without any active logins to Azure/Outlook 365 to avoid user conflicts during the configuration.

App Registration

Search for app registrations and open it

You can proceed with a new APP Registration (API), by clicking on “New registration” button:

On App Registration we can proceed entering the following information:

  • Name for the new App,
  • Supported Account as “Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)”,
  • Redirect URI as “Web” type (Previously generated and copied from Deepser Oauth Client) [LINK TO “Deepser Oauth Client Creation” section]

In conclusion you can click on “Register” button.

App Authentication

You can now access your newly registered application and navigate to ‘Manage > Authentication’ from the menu.

From here, you can confirm that the correct Redirect URI is set under the ‘Web’ section, and enable the following tokens:

  • Access tokens (used for implicit flows)
  • ID tokens (used for implicit and hybrid flows)

App Certificate & Secret

Under “Manage > Certificates & secrets” in the menu, you can create a secret. During the configuration process, you’ll need to set its expiration time and copy its value, which will be used later to complete the configuration in Deepser.

The copied secret value will need to be entered into the field “Client Secret” on the oauth client record in Deepser:

Notes:

  • Be sure to copy the value of the secret, not the Secret ID.
  • You must copy the secret value during the creation phase, as you won’t be able to access it later (in that case, you would need to recreate it).
  • If you set an expiration for the secret, remember to renew it before the expiration date

App Token configuration

Under “Manage > Token configuration” from menu you can set the following optional claim IDs by clicking on “Add optional claim”:

  • acct
  • email
  • family_name
  • given_name

When adding the claims, remember to check the box for “Turn on the Microsoft Graph email, profile permission (required for claims to appear in the token)”:

App API permissions

Under “Manage > API permissions” in the menu, you can add the following permissions for Microsoft Graph and then run the “Grant admin consent” action:

  • email as Delegated permission
  • offline_access as Delegated permission
  • openid as Delegated permission
  • profile as Delegated permission
  • User.Read as Delegated permission

Also at this stage, if you need to Provision user/groups in Deepser, you need to add permissions for:

  • User. Read All as Application permission
  • Group. Read All as Application permission

Click on “Add a permission” to open the permission selection prompt:

Then select “Microsoft Graph” as API permission to use:

From that screen you can choose Delegate or Application permissions and use the search field for research the desired permission to add:

After adding all desired permissions, you can run Grant admin consent command:

Enterprise Application

Now you can switch to “Enterprise Applications” by searching for it in the global search:

Then search and access your new registered application clicking on it:

After access to it, go to its properties and change the following configurations:

  • “Enable for user to sign-in” to YES
  • “Assignment require” to YES

Users and Groups

To enable provisioning for users and groups in Enterprise Application you can add your desired users and groups:

Now that everything is configured in Azure, you can go back to the Oauth Client in Deepser.

Azure > Deepser Configuration

Before going back to the Oauth Client in Deepser, we can note down all the Azure information to be used in Deepser Oauth client configuration. Below is a summary of the Azure information to be reported in Deepser:

Secret Value

The “Secret value” will be entered “Client Secret” field in Deepser (“General” Tab):

Notes:

  • Be sure to copy the value of the secret, not the Secret ID.
  • You must copy the secret value during its creation phase, as you won’t be able to access it later (in that case, you would need to recreate it).

Application (client) ID

The “Application (client) ID” will be entered “Client ID” field in Deepser (“General” Tab):

Directory (tenant) ID

The “Directory (tenant) ID” will be entered “Tenant ID” field in Deepser (“Provisioning” Tab):

Deepser Oauth Client Configuration Completion

You can now return to the Deepser Oauth Client record to proceed with the completion of configuration.

Deepser – General Tab

If not already done, please configure “Provider” and “Type” field respectively as “Azure” and “User”.

Then we can proceed to set Client ID and Client Secret:

In the “Client ID” field, enter your “Azure application ID”, which you can find in the overview section of the app registration

In the “Client Secret” field, enter the value you copied earlier when creating the secret

Deepser – Users Tab

In the “Users” tab, you will need to fill the highlighted fields:

  • Username Attribute: userPrincipalName
  • Endpoint Users Data: https://graph.microsoft.com/v1.0/me
  • Users Field: to be set as shown in the image below.

In this tab you can specify field mapping between Deepser and Azure, and you can also populate other fields and perform processing in Deepser upon creating/updating a user via the User Create Expression and User Update Expression fields.

Deepser – Provisioning Tab

If you want to enable users and groups provisioning, you can do it from “Provisioning” Tab.
In the provisioning tab you will need to fill in the fields highlighted in the figure:

In the “Tenant ID” field, enter your “Azure Directory (tenant) ID”, which you can find in the overview section of the app registration (like the Client ID):

After completing the configuration, you can return on the “General” Tab, and click on the “Validate” button and check if the connection between Deepser and Azure works well.

Note: We recommend performing validation in incognito mode or in a browser without any active logins to Azure/Outlook 365 to avoid user conflicts during the configuration.

For doing this, you can copy validation URL directly from “Redirect URI” field:

By clicking the provision button, you can check the configuration, and the users/groups selected in the Azure app should now correctly imported into Deepser.

You can also configure a Cron Expression to automatically run the provisioning at scheduled times.

Also refer to this article, for a better understanding of the fields in this form.

Email Integration

Email integation is a very important module for the organizations that adopt a Service Desk software, in order to interact with their customers and to improve the collaboration between team members.

Deepser is designed to provide a web platform in order to avoid a large number of email messages and so defining a shared and orderly way to manage a service.

It’s clear, however, that the email notifications to customers (or operators) can be a plus for our service.

In addition to set up a web portal, we can give other communication channels like emails to that users who want the “security” of an email confirmation after their request.

Fundamental entities of the Deepser email integration are:

  • Mailbox: the email addresses managed to send or receive notifications.
  • Events: talking about outgoing emails, an event is used to define when sending a notification.
    It is possible to define an infinite number of events to notify our users.
  • Templates: the templates (subject, body and layout) of the outgoing emails.
  • Messages: the email messages sent or received by the system. This entity it’s not directly visible in the Email module, because every message (and their attachments) are only visibile inside the forms of the entity they are linked to (eg: a message related to an Operation in the module “Service”, or an email sent about an asset of the CMDB).

Articles

  • Email Integration in Service Management
  • Enable Embedded Images on Message Body
  • Mailbox
  • Configuring an Outgoing Mailbox
  • Configuring an Incoming Mailbox
  • OAuth Client for Email Integration
  • Email Loop Management Tool
  • AZURE OAUTH CLIENT
  • Google Oauth Configuration
  • Email Rules
  • Email Rule Configuration
  • Advanced Email Rule Configuration
  • Avoid Duplicate Tickets By Email
  • Managing additional Email recipients
  • Email Events
  • Enabling / Disabling an Email Event
  • Custom Email Events Creation
  • Custom Email Events Configuration
  • Attach Report to Email Notification
  • Email Templates
  • Email Template Configuration
  • New operation notification template for Requester User
  • New or Updated comment notification template for Requester
  • Email Webclient

Email Integration in Service Management

Emails are integrated into the operations of service management.

With the appropriate configuration of email events, messages are automatically generated to notify customers, technicians or operators.

Through the message subject Deepser can also recognize incoming emails that refer to an existing entity in Deepser and associates them.

In order to see all the email messages associated with, for example, a service operation and/or its related entities (Comments, Worklog or Task) there is a dedicated field, the Email List.

By default this field is added to the operations screen, in the Email tab.

From the Email List field you can understand which emails are incoming and which are outgoing.

Email List also shows: subject, date of receipt or sending, sender and recipients.

By clicking on the “lens” icon, you can view the message body.

COMMENTS AND EMAIL

Most of the time you want that to each comment, added to a service operation, corresponds an email notification send to other actors. Deepser proposes this configuration as default.

If, for example, a technician in charge of the resolution of an issue needs more information from the user, he can request it by adding a comment inside the issue.

Deepser then sends an email, containing the technician’s request, to the user who will respond with the required information.

The user’s email will be “linked” with the issue and a comment will be created from its content.

The technician will receive a notification from Deepser containing the user’s response and will then be able to complete the issue resolution activities and close it.

Enable Embedded Images on Message Body

In Deepser, by default, images, embedded in the body of incoming emails, are saved as attachments to the email message and not included in the body and saved, for example, within the Description field.

Images can still be viewed from the Email List grid, in the operation form, in the Attachments column.

NOTE: By enabling this option the size of the Database can increase considerably over time, for this reason by default it is disabled.

To enable this option go to the system configuration menu: System->Configuration->General->Email->Attachment

Set ‘Embedded Images on Message Body‘ option to ‘Yes‘.

Mailbox

Using Mailboxes, Deepser can Receive and Process Emails, send Notifications, etc.

There are no limits about the number of email addresses that can be integrated, nor on the provider.

 

Configuring an Outgoing Mailbox

Mailboxes are one of the fundamental entities in email integration.

In order to send emails to your users, in fact, you need to define an outgoing mailbox, in this guide we are going to explain the procedure for its setup.

CONFIGURATION

To configure a mailbox in Deepser, in the backend navigation menu, navigate to the System->Tools->Email->Mailbox section.

The grid in this section shows mailboxes already configured in Deepser.

To configure a new mailbox click on the ‘+ Add Mailbox‘ button in the top right corner.

At this point the mailbox configuration form will open.

Once the mailbox type has been set, in this case ‘OUT‘, all fields for the outgoing mailbox configuration will be loaded dynamically.

The fields in the form have the following meaning:

TABFIELDMEANING
GENERAL DATANameName of the mailbox. It is a descriptive field used in the system to display the mailbox.
 TypeIN or OUT (IN to receive emails, OUT to send emails).
 StatusIf “Disabled” the email integrations will not be active.
 Email DisplayThe displayed email address. It is not the username. The username is used to access the email, this field is only the displayed email address if our server allows us to use a different email address for the outgoing messages.
 Display NameThe name displayed in the “From” field of the emails (eg: Your Service Desk).
 HostThe address of the mailserver. It depends on your provider or mailserver.
 DoorPort for the connection to the mailserver.
 EncryptionEncryption of the connection to the mailserver. It depends on your provider or mailserver.
 User NameUser name (usually the email address) to connect to our mailbox.
 PasswordPassword to connect to our mailbox.
 ProtocolProtocol to send emails (SMTP or OWA). It depends on your provider or mailserver.
 OAuth ClientOAuth2 client used for the  authentication on services that require it.
SITEMA DATAPrefixIt’s the prefix to prepend to the unique field of the record (usually the ID) sent by email. The Prefix is mainly used in the Subject of the email by the incoming integration (mailbox IN), to tell Deepser if it has to create a new record or to update an existing one. To give an example, if we are sendind an email for a Service Operation record, we can define that the prefix is “TICKET#”. By doing so, the emails will be sent with the subject “TICKET#ID” (where ID is the unique number of the Service Operation). If the user answers that email must not delete this text, to make Deepser aware of the record the email is referring to.
 Allowed EmailsIt tells if emails can be sent only to users registerd in the system or to any email address.
 Is Default OutgoingIt tells if the email is the default to send notifications. Deepser lets configure an infinite number of mailboxes, but the system needs to know which is the default one to send notifications. Every Service Operation record, for example, contains a field called Mailbox ID, that represents the email address to send the notifications for that record. If this field is not filled, then the emails will be sent using the Default Mailbox.
 Exclude ExpressionIn this field you can insert a regular expression in order to block emails whose recipients match the defined expression.
ADVANCEDCustom CodeCustom PHP code executed after an email has been sent. It is possible to configure this field to trigger custom events. For example, if we wanted to update a counter of the reinders or update a specific entity of Deepser, we could exploit the customization of this field.

Once the form has been filled and the configuration saved, click on the ‘Check‘ button, top right, to test the configuration.

If the mailbox has been configured correctly you will see a message of successful connection, otherwise an error message.

Configuring an Incoming Mailbox

To be able to create entities, from incoming emails, it is necessary to define an incoming mailbox, and then associate this mailbox to related email rules.

This guide will explain how to configure an IN mailbox.

Important Note: based on the settings of your email server, all incoming messages could be deleted after Deepser has processed them. This is the default behaviour of the software with email servers like Exchange, Standard SMTP Servers, etc.

Be very careful when configuring the incoming email integration, do a test and a backup. Remember also that Deepser processes all the emails in the inbox, so if the mailbox is full of messages (eg: the first time we run the integration) a lot of records could be created.

To avoid this situations, not directly caused by Deepser, we advise always to do a test on mailboxes with few messages.

CONFIGURATION

To configure a mailbox within Deepser, in the backend navigation menu, navigate to the System->Tools->Email->Mailbox section.

The grid in this section shows already configured mailboxes.

To configure a new mailbox click on the ‘+ Add Mailbox‘ button in the top right corner.

At this point the mailbox configuration form will appear.

Once the mailbox type has been set, in this case ‘IN‘, all the relevant fields will be loaded dynamically.

The fields in the form have the following meaning:

TABFIELDMEANING
GENERAL DATANameName of the mailbox. It is the name used in the select-boxes.
 TypeIN o OUT (IN to receive emails, OUT to send).
 StatusIf “Disabled” the integration will not be considered by the system.
 HostAddress of the mailserver.
 PortPort for the connection to the mailserver.
 EncryptionEncryption of the connection..
 UsernameUser name to read the mailbox (usually it is the email or the Exchange user associated to that mailbox).
 PasswordPassword to login to the mailbox.
 ProtocolProtocol to get the emails (POP3, IMAP or OWA).
 OAuth ClientOAuth2 client used for the authentication, if required.
SITEMA DATAModelThe field Model represents the entity of Deepser in which to look for a record linked to the received emails. If we set for example DeepService – Operation the mailbox will create and update records of Operations. If we set DeepAdmin – User the emails will used to create or update users.
 Model FieldIt is the field of the entity Model where to check if a record already exists. If we set the ID (field: entity_id), then the check will be done on entity_id (unique ID) of the Operations.
 PrefixIt’s the prefix we prepend to the Model Field, to search the record. If we set the Model Field equals entity_id of the Operation, then the email integration verifies the subject of the email: if after the Prefix there’s an ID of a record already in the system. After the expression Prefix and until the first blank space, the ID of the model will be searched. Thus, if we set the field Prefix with the value TICKET# and the Model Field with the value entity_id, if we receive an email with subject TICKET#70, then Deepser looks for an Operation with ID 70. If Deepser finds that record, then the record is updated and the rules applyed to update the record are that in the Update Expression field. If we receive an email with a subject Hey this is a new ticket then Deepser creates a new record, following the rules in the field Create Expression.
 Outgoing Email BoxWe can teel the system that for every record created using this mailbox we will use the specific outgoing mailbox to send notifications.
 Apply Email RulesIf yes related email rules are executed.
 Allowed EmailsIf we can receive email from all emails or only from registerd users. Ignored mails will be deleted.
 Spam ExpressionIn this field it’s possible to define a regular expression to check the objects of incoming mails in case they should be identified as spam. If the emails are ignored they are deleted from the inbox.
ADVANCEDCron ExpressionCron Expression that defines the frequency of the scan of Deepser. If this expression is not set, this mailbox will not be processed by Deepser.
 Processed onDate and time of the last scan of the mailbox.
 Custom CodePHP custom code run after the email has been received. It is possible to configure this field to trigger custom events after the email has been received. For example, if we want to receive a counter of the reminders or to update a specific entity of Deepser after we have received the email, we can customize this field to do that.

Once the form has been filled and the configuration saved, click on the ‘Check‘ button, top right, to test the configuration.

If the mailbox has been configured correctly you will see a message of successful connection, otherwise an error message.

OAuth Client for Email Integration

Some systems require web applications, such as Deepser, to perform authorization before they can use their services.

Deepser allows you to configure multiple OAuth clients in order to authorize it , through the OAuth2 protocol, on different services.

CONFIGURATION

To configure an OAuth client in Deepser, navigate to the System-> Tools->OAuth->Client section.

You will see a grid containing all oauth clients defined as Deepser.

To configure a new client click on the ‘+ Add Client’ button in the top right corner.

A new OAuth Client can be also created and configured from the configuration form of a mailbox.

Under the OAuth Client field, of the Select type, whose options are the already configured clients, clicking on the ‘+’ icon allows you to create a new client, while clicking on the ‘pencil‘ icon allows you to modify the configuration of the selected client.

The fields of the configuration form of an OAuth client are listed and explained below:

FIELDMEANING
Redirect UriDeepser Url from which Deepser which will send requests to the provider. The URL must be authorized in the administration panel of provider. The URL will appear once the client is saved. After saving, the ‘Validate‘ button will appear, by ckicking it you can authorize the client once its configuration is complete.
NameClient name. It represents a descriptive field with which the client will be displayed in the system.
ProviderProvider: Google, Azure, Generic. If you use Google or Azure as a provider the only other fields that must be filled are Client ID, Client Secret and status. Generic value is used to configure the authentication to all other providers.
Client IDPublic identifier for applications. It is provided by the provider, usually when a new application is authorized.
Client SecretSecret part of the authentication credentials. It is provided by the provider.
TypeType of data you want to access/recover.
ScopeScopes to which the application requires access. No need to fill it for Google or Azure providers, default values will be used.
Url AuthorizeIt is the ‘base URL’ of the Identity Provider that manages OAuth 2 authentication. No need to fill it for Google or Azure providers, default values will be used.
Url Access TokenThis is the ‘base URL’ to which the parameters for requesting the authentication token are added (post-authorization step). No need to fill it for Google or Azure providers, default values will be used.
ProxyIP address and port of any used proxy. It is not necessary for Google or Azure providers, default values will be used.
VerifyIf a proxy has been configured you can enable or disable the SSL check. No need to fill it for Google or Azure providers, default values will be used.
StatusIf ‘disabled’ the client is not active.
Scope Separator CharCharacter used to separate different scopes. Used during the construction of the request url. No need to fill it for Google or Azure providers, default values will be used.
Endpoint User DataIn case the OAuth configuration is User type and the User Data Source is set to ‘Endpoint’, once the authentication is done with the Identity Provider the user data is retrieved by connecting to this endpoint. No need to fill it for Google or Azure providers, default values will be used. No need to fill it for Email Box type.
Related LDAPsAny LDAP integrations already configured, whose users must be linked. No need to fill it for Email Box type, the default values will be used.
Username AttributeAttribute (field) that desctibe the user’s username. No need to fill it for Google or Azure providers, default values will be used. No need to fill it for Email Box type.
User FieldsMaps the user (Deepser entity) attributes to those retrieved from the specified user data endpoint. No need to fill it for Google or Azure providers, default values will be used. No need to fill it for Email Box type.
User Create ExpressionPHP code for configuring the user creation, for example in case of an SSO integration. No need to fill it for Email Box type.
Login Button CaptionButton label for access via SSO. No need to fill it for Email Box type.
Login Button IconIcon displayed on the SSO authentication button. No need to fill it for Email Box type.
Access TokenThis field is not filled out in the form for security reasons. It contains the serialized access token.
Original Access TokenThis field is not filled out in the form for security reasons. It contains the serialized access token.

Once the form has been completed and the OAuth client configuration has been re-saved, you can validate it.

Just click on the ‘Validate‘ button that will appear once the client is saved for the first time.

Authenticate on Provider through the form that will appear, once logged in the client is authorized.

Email Loop Management Tool

In Deepser there is an integrated tool that allows you to mitigate and block email loops, blocking the receipt of emails from email addresses that have sent a large (configurable) number of emails in a defined time interval.

 

EMAIL LOOP MANAGEMENT TOOL ENABLING GUIDE

To enable the Loop email management tool, you will need to go to the System-> Tools -> Email->Mailbox menu

Once here we will have to go to the configuration of the email input boxes, if it is necessary to configure the tool for multiple email boxes it will be necessary to follow this guide for each entry box.

You will now need to click on the edit button of the form template in the upper left part of the page:

At this point we will have to go to configure a new tab “Email Loop Configuration”, the name can be configured if necessary.

To configure the new tab, you will need to right-click on the tab item and click “New Tab”.

Now you will need to click on the Newly created “New Tab” entry:

Here we are going to change the “Label” field with the name we want to give to this new tab, in our case Email Loop Configuration

Now we will have to click the “SAVE” button to save to the configuration.

At this point we will have to go to configure a new Fieldset “Email Loop Settings”, the name can be configured if necessary.

To configure the new tab, you will need to right-click on the tab item and click “New Fieldset”.

To rename the fieldset you will need to click on the new fieldset just created, at this point you can rename the fieldset by changing the head present in the campo at the top center of the page:

In our case we will rename it to “Email Loop Settings”.

At this point we must enter the following fields in this fieldset:

  • Allowed Messages Interval
  • Allowed Messages Number
  • Lock Duration
  • Whitelist Expression
  • Blacklist
  • Message Logs

Once done it will be possible to change the width of the fields through their settings in order to make it easier to fill them in and consult, the final result will have to look like this:

Finally, we will have to go and click the “SAVE” button to save the changes to the form template.

 

EXPLANATION FIELDS EMAIL LOOP MANAGEMENT TOOL

After configuring the form as described in the previous step we will have in the “Email Loop Configuration” tab a structure similar to this:

Below is the list of fields with their description:

FieldDescriptionNotes
Allowed Messages IntervalThe time interval in which the number of messages received from an email address will be evaluated 
Allowed Messages NumberNumber of messages allowed per email address in the time interval defined in the “Allowed Messages Interval” field 
Lock DurationThe duration of the block on receiving messages if an email loop is detected. 
Whitelist Expressionthis field is a regular expression (regex) which will instruct the system to exclude all email addresses that match this regular expression 
BlacklistHere you will see the list of blocked email addresses and until they are blocked 
Message LogsHere you will see the list of blocked email messages 
 

EXAMPLE EMAIL LOOP MANAGEMENT TOOL CONFIGURATION

Suppose you want to configure the email management tool to block all email addresses that send more than 30 messages in 5, minutes for 15 minutes but you want to exclude from this rule all addresses that belong to the domain example.com eg.  test@example.com

To do this you will need to configure the fields as follows:

  • Allowed Messages Interval set to 5 minutes
  • Allowed Messages Number set to 30
  • Lock Duration set to 15 minutes
  • Expression whitelist set to:
[\w+|\.] +@example\.com

Below is an image of the final result:

At this point you will need to click on “Save” or “Apply” to save to the configuration

AZURE OAUTH CLIENT

This guide explains step-by-step how to set up a new OAuth client to integrate Office365 with Deepser. To do this you will need to create a new APP Registration in Azure.

Before starting the setup, it is necessary to retrieve your Tenant ID, which is required for the first step of the configuration.

You can do it searching and accessing Microsoft Entra ID Overview page:

OAUTH CLIENT CREATION IN DEEPSER

In Deepser, go to the menu item System -> Tools -> Oauth -> Client.
 Then click the blue Add Client button.

Then set:

  • Name
  • Provider: Azure
  • Type: Mailbox
  • Tenant ID

Then click Apply or Save.

Once the save is completed, the redirect URI will be generated:

We can then proceed to copy the redirect URI that we will use in the next configuration step.

CREATING YOUR APP ON AZURE

Go to the Azure portal and sign in with your Office 365 account.

Once logged in, click on App Registrations.

Then click New Registration.

Give a name to the application and in Supported Account Types, set the Single Tenant (first item).

Scrolling, set the Redirect URI: set Web in the first drop-down menu.

In the second field you need to paste the URI provided by the OAuth client provided in Deepser.
Then return to the configuration of the OAuth client in Deepser and copy the URI that we find under the Validate button (the URI will be generated in Deepser after the first save of the client).

Then return to the application registration in Azure and paste the URI.
Finally, click on Register.

AZURE APP CONFIGURATION

Once the app is created, click on Authentication, item in the left menu.

Scroll down the page and tick the access tokens and ID tokens.
Then click Save.

Go now to the Certificates and Secrets
 item on the side menu. Click on the Client Secrets tab and generate a new Client Secret through the New Secret Client button.

Then enter a Description, a Deadline and click Add.

Once the Client Secret is generated you need to copy its Value and paste it on the Client Secret of the OAuth Client into Deepser.
Attention: the value of the Client Secret will be viewable only at the first generation. After that it will be censored and it will no longer be possible to view or copy it.

In the Client ID in Deepser you need to paste the Application ID.
The ID of the application can be retrieved in the Menu item Overview.

Then save the changes to Deepser.

Go now to the API permissions through the API Permissions in Azure menu item and click Add a permission.

In the Microsoft API tab, select the Microsoft Graph APIs.

Then select Delegated Permissions.
Then tick the entries of the following permissions:

  • Offline_access
  • Mail.ReadWrite
  • Mail.Send
  • IMAP.AccessAsUser.All (optional if using POP)
  • Pop.AccessAsUser.All (optional if using IMAP)
  • SMTP.Send

You can search for these permissions by searching for these permissions.
Once selected, click Add Permissions.

Once you have added permissions, you must grant administrator consent via the Grant Admin Consent for Deepser button. Confirm by clicking Yes in the popup.

OAUTH CLIENT VALIDATION

Once the Client has been configured, it must be validated through the appropriate Validate button.

NOTE: The user who validates the Client must have an active Office 365 license and must be able to access the mailboxes on which you want to use the OAuth client.

Also make sure that the user with whom you are validating the Client has enabled the following protocols in the user settings with which you will validate the client within the admin area in Office 365:

  • IMAP
  • Pop
  • Authenticated SMTP.

If you use shared mailboxes, make sure that IMAP and POP services are enabled in them.

If the validation is successful, we will be returned to the Client configuration with a green message at the top that tells us the successful completion of the validation.

Now go to the configuration of the incoming box in Deepser via the menu item System -> Tools -> Email -> Mailbox and select the incoming box.

In the OAuth Client field, select the OAuth Client that you just configured and validated.

Then save your changes.

To verify that the box is working correctly, you can use the Check button.
If everything works, the Check will return a message in green with the message “Connection Successful”.

Google Oauth Configuration

Create an OAuth Client in Deepser for Mailbox

In the Deepser Configuration, navigate to System > Tools > OAuth > Client > Add Client:

Enter a name, define the type  as  Mailbox, set the provider as Google and save.

Once saved, copy the generated Redirect URL.

Go to the Google Cloud Platform, and log in. Once this is done, click on  the  menu at the top where all the projects are listed.

A window will open where you can create a new project using the New Project button. All you have to do is give your new project a name and click on the Create button.

To enter the newly created project  , repeat the process above:  click on the menu that groups all the projects and click on the name of the newly created project to start the configuration.

Once you have entered the project, click  on the APIs & Services (1) > OAuth Consent Screen  (2) section in the menu on the left.

In User Type select External and proceed by clicking Create.

Give the application a name, enter the email used for access  in User Support Email and in Developer Contact Information. Proceed to Save & Continue.

Under Scopes, press the Add or Remove Scopes button.

In the form below the paragraph Add Manually, copy and paste the following address https://mail.google.com/. Then  click Add to Table, and then  click Update. Then click save and  continue to continue.

In  the Trial Users section, click on Add User and enter the email address with which you logged in to the platform.

Now go to  the Credentials  section of the menu on the left and create a new Oauth Client ID through the Create Credentials button.

In the drop-down menu, select OAuth Client ID.

Select in  the application type Web Application, give it a name, and under Authorized Redirect URIs,  paste the URI that you previously generated and copied. Finally, click Create button.

The Client  ID  and Client Secret will be generated and copied and entered into the respective fields of the OAuth Client previously started to configure in Deepser.

Once saved, proceed with the Client Validation by clicking on the Validate button.

Then log in and click Continue.

Tick the boxes regarding the read/write permission of Google Mail and click Continue.

If all the steps have been carried out correctly, the Oauth Client will be validated and active.

Email Rules

INTRODUCTION

After you have configured an incoming mailbox you can associate it with the Email Rules.

When receiving an email, according to the logic configured in the rules, entities can be created in Deepser.

A typical case is the one in which you want to create, from the received emails, operations (ticket), or comments associated with them.

APPLICATION RULES

You can specify when execute the rule:

  • On Create: Deepser recognizes the message as the beginning of a new thread, i.e. the email subject does not contain the specified prefix (defined in the incoming mailbox configuration) or the ID is not associated with any entity of the model indicated as the main mode (in the incoming mailbox configuration).
  • On Update: Deepser recognizes the message as related to an already existing entity.
  • Always: For each message.

PRIORITY

To each rule can be assigned a priority, that determines the rules execution order.

The higher the value, the sooner it will be executed.

Only one rule can be executed for each message, so the first rule of the stack, whose filter condition is checked. is executed, remainings are ignored.

So it is very important to choose correctly the priority of each rule. Especially when you have multiple email rules not mutually exclusive.

EMAIL RULE CREATION

You can create new email rules in two different ways: actually create it or duplicate an existing one.

CREATING AN EMAIL RULE

Go to the Emailà Toolsà Systemà Rule and click on the ‘+ Add Rule‘ button in the top right corner.

DUPLICATE A RULE

You can create an email rule by duplicating an existing one. By doing so, the new rule will inherit all configurations of the original one. They will only differ for the name to which the suffix “(copy)” will be added.

To duplicate an existing rule, from its form click on the ‘Duplicate Rule‘ button in the top right corner.

Email Rule Configuration

To configure an Email Rule go the Rule Email->Tools->System section.

Click on a rule already defined (in grid) or the ‘+Add Rule‘ button.

At this point the configuration form will be displayed.

The form fields have the following meaning

FIELDSIGNIFIED
NameRule name. Descriptive field with which the rules will be displayed in the system.
PriorityPriority assigned to the rule. The higher its value the sooner it is evaluated in the applicable rule queue.
MailboxMailbox for which the rule must be applied.
Apply OnSelect which allows you to specify when a rule is to be applied: Always, On Create, On Update.
StatusThe status (enabled/disabled). If “Disabled” the rule will not be active.
Email Message FilterIn this field, through the query builder or by entering PHP code in the scripting area, you can specify the conditions that the incoming message must meet. If the conditions are met the rule is executed.
Set main model valuesIn this field, through the query builder or by inserting PHP code in the scripting area, it is possible to specify how the fields of the main template (defined in the mailbox configuration) should be valued when the rule is executed.
Related Model AliasThis field, if filled, defines the model of the “weak” entities to put in relationship with the main model. A typical case of use is in the ‘On Update’ events, when a new message doesn’t have to create an operation but a comment related to the existing one.
Set related model valuesIn this field, through the query builder or by inserting PHP code in the scripting area, you can specify how the fields of the related model should be valued.

Advanced Email Rule Configuration

In case you need to configure Advanced Email Rules you can define them using PHP code instead of using the available query builder.

You can insert custom code in the ‘Email Messages Filter‘ ‘Set Main Model Values‘ and ‘Set Related Model Values‘ fields, to access their scripting area just click on the </> button.

Avoid Duplicate Tickets By Email

In this example we want to configure a custom Email Rule, in order not to create a new operation, if one already exists in open status.

The “duplicate” email will be added as a comment to the already open ticket.

STEP1: SET THE MAIN FIELDS OF THE RULE

As a first step set the basic fields of the rule: Name, Priority, Mailbox, Status.

Set the ‘Apply On‘ field to ‘On Create‘, this will intercept all those emails that are not recognized as part of an already existing thread (for example through the pattern TICKET#).

Set, in the field ‘Related Model Alais‘ the model ‘DeepActivity – Activity‘, to sepcify that a comment will be added to an operation.

STEP2: CONFIGURE THE FILTER

Messages that meet all of the following conditions, when compared to an operation, will be considered duplicates:

  • The sender is also the Requester User of the operation
  • The subject of the email is the title of the ticket
  • The operation is, at that moment, not closed/eliminated

To configure the filter, enter the following PHP code in the ‘Email Messages Filter‘ field

				
					//JSON that manage what the querybuilder shows in this case 'Body Text equal READ CODE ABOVE'
/** START_RULES
{"condition":"AND","rules":[{"id":"body_text","field":"body_text","type":"string","input":"text",
 "operator":"equal","value":"READ CODE ABOVE"}],"valid":true}
END_RULES */
 
//parse the sender and normalize the email address
$fromString = '';
$from = Deep::helper('deep_util')->parseEmailString($this->getMessage()->getFrom());
if (count($from)){
    //get normalized address
    $fromString = array_keys($from)[0];
    //load the user corresponding to that email address
    $fromUser = Deep::getModel('deep_admin/user')->loadByEmail($fromString);
    //if exists retreive his username
    $fromUsername = $fromUser && $fromUser->getId() ? $fromUser->getUsername() : $fromString;
    //retreive the message subject
    $mailSubject = $this->getMessage()->getSubject();
    //retreive all open status
    $openStatusValues = Deep::helper("deep_list")->getStatusValues(
        Deep_Service_Model_Operation::LIST_CODE_STATUS,
        Deep_List_Model_Listclass::TYPE_OPEN);
    //retrieve a collection of operations that meet the following requirements
    $operations = Deep::getResourceModel('deep_service/operation_collection')
        ->addFieldToFilter('status',['in' => $openStatusValues])
        ->addFieldToFilter('requester_username',['eq' => $fromUsername])
        ->addFieldToFilter('title',['eq' => $mailSubject]);
    //if at least one exists
    if(count($operations)){
        //save its id on the request
        Deep::register('custom_email_rule_operation_model_id',$operations->getFirstItem()->getId());
        //save sender username on the request
        Deep::register('custom_email_rule_message_from_username',$fromUsername);
        //return true means that the message is a duplicate
        return true;
        //then the code in the field 'Set Main Model Values' is executed
    }
}
//not all the conditions to define the message as duplicate have been met
return false;
				
			

STEP3: CONFIGURE/SET THE MAIN MODEL

Through the field ‘Set Main Model Values‘ set the operation, retrieved in the field ‘Email Messages Filter”, as main model to which the message must be added as comment.

Insert the following PHP code in the scripting area.

				
					//JSON that manage what the querybuilder shows in this case 'Description equal READ CODE ABOVE'
/** START_RULES
{"condition":"AND","rules":[{"id":"description","field":"description","type":"string","input":"text",
"operator":"equal","value":"READ CODE ABOVE"}],"valid":true}
END_RULES */
 
//set message as non-creator. Because it doesn't create a new main model.
$this->getMessage()->setIsCreator(0);
//retreive operation id from the request (added in the code of the 'Email Messages Filter' field)
$operationId = Deep::registry('custom_email_rule_operation_model_id');
//load the operation and set it as main model
$this->setModel(Deep::getModel('deep_service/operation')->load($operationId));
return $this->getModel();
				
			

STEP4: CONFIGURE COMMENT CREATION

Through the field ‘Set Related Model Values‘ configure the creation of the comment in relation with the main model, set in the field ‘Set Main Model Values‘.

Inserting the following PHP code in the scripting area.

				
					//JSON that manage what the querybuilder shows in this case 'Description equal READ CODE ABOVE'
/** START_RULES
{"condition":"AND","rules":[{"id":"description","field":"description","type":"string","input":"text",
 "operator":"equal","value":"READ CODE ABOVE"}],"valid":true}
END_RULES */
//retreive operation id from the request (added in the code of the 'Email Messages Filter' field)
$operationId = Deep::registry('custom_email_rule_operation_model_id');
//delete operation id from the request
Deep::unregister('custom_email_rule_operation_model_id');
//retreive sender username from the request (added in the code of the 'Email Messages Filter' field)
$fromUsername = Deep::registry('custom_email_rule_message_from_username');
//delete sender username from the request
Deep::unregister('custom_email_rule_message_from_username');
//Create new Activity
$comment = Deep::getModel('deep_activity/activity');
//Set type Comment (1=>Comment, 2=>Worklog)
$comment->setType(1);
//Set the main model (operation in this example) alias
$comment->setModelAlias('deep_service/operation');
//set the id of the operation to which the comment should be added
$comment->setModelId($operationId);
//set the email body as Comment description
$comment->setDescription($this->getMessage()->getBody());
//set sender as user who created the comment
$comment->setCreatedBy($fromUsername);
//set comment as visible to end users
$comment->setPortalVisibility(1);
//save the comment
$comment->save();
				
			

Managing additional Email recipients

In this example you want to create a custom Email Rule to store all the recipients of an email that generates a new operation, and then eventually add them in Cc to the notifications generated during its life cycle.

Two new custom fields will be created in the operations, one to manage recipients who are also registered users in Deepser, the other to store only email addresses.

STEP1: CREATE CUSTOM FIELD FOR REGISTERED USERS IN DEEPSER

Create a custom field in the DeepService – Operation model with the following characteristics:

  • Column Name: cust_operation_cc_registered
  • Label: Additional Recipients
  • Column Type: Don’t create DB clumn
  • Element Type: Userassociation

STEP2: CREATE CUSTOM FIELD FOR UNREGISTERED USERS IN DEEPSER

Create a custom field in the DeepService – Operation model with the following characteristics:

  • Column Name: cust_operation_cc_unregistered
  • Label: Additional Recipients (Not Registered)
  • Column Type: Text area
  • Element Type: Textarea

STEP3: EMAIL RULE CREATION

 Create a new Email Rule, set name, priority (higher than a possible default rule) and status ‘Enabled’.

Set, in the ‘Apply On’ field the value ‘On Create‘ to indicate that the Email Rule should be executed if the message does not belong to an existing thread.

STEP4: EMAIL RULE CONFIGURATION

In the “Set Main Model Values” Query Builder, Set the following values:

 

Insert in the scripting area of the ‘Set Main Model Values‘ field the following PHP code, which implements the logic for saving, on the operation custom fields, any additional recipients.

				
					/**
 * Additional Recipient Managment
 **/
//retreive already parsed Tos
$to = Deep::helper('deep_util')->parseEmailString($this->getMessage()->getTo());
 
//retreive already parsed Ccs
$cc = Deep::helper('deep_util')->parseEmailString($this->getMessage()->getCc());
 
if((!is_null($cc) && is_array($cc) && !is_null($to) && is_array($to) )) {
    //merge to and cc arrays, and change keys case
    $recipients = array_change_key_case(array_merge($to,$cc), CASE_LOWER);
      
    //exclude incoming mailboxes defined in deepser to avoid loops
    $mailboxCollection = Deep::getResourceModel('deep_email/mailbox_collection')
        ->addFieldToFilter('type',['eq' => 1]);
         
    foreach($mailboxCollection as $mailbox){
        if($mailbox->getUsername()){
            unset($recipients[strtolower($mailbox->getUsername())]);
        }
    }
     
    //manual exclusion other emailboxes that forward emails to deepser to avoid loops
    //unset($recipients['']);
     
    $ccUnregistered = [];
    $ccRegistered = [];
     
    //for each additional recipient determine if it is a registered user or not
    foreach($recipients as $recipient => $name){
        $user = Deep::getModel('deep_admin/user')->loadByEmail($recipient);
        if($user && $user->getId()){
            //populate userassoc array
            $ccRegistered [] = $user->getUsername();
        }
        else{
            //populate unregistered user array
            $ccUnregistered [] = $recipient;
        }
    }
     
    if(count($ccRegistered)){
        //populate the userassociation, that is the cust_operation_cc_registered field
        $this->getModel()->addUserAssociations('watch', $ccRegistered);
    }
     
    if(count($ccUnregistered)) {
        //populate the custom field cust_operation_cc_unregistered, adding email addresses separated by ;
        $this->getModel()->setData('cust_operation_cc_unregistered', implode(';', $ccUnregistered));
    }
}
				
			
Note: If the user association is populated by a rule that does not make any changes to the ticket or in general to the entity to which the user association belongs, the user association will not be modified.

Email Events

Mail events are a tool closely related to Deepser mail integration.
The Mail Events configuration allows you to define:

  • When a notification must be sent
  • Which notification must be sent
  • Who are the recipients of the notification email

The emails are generated by dynamically enhancing the Template set in the event as the notification template.

Deepser contains multiple default mail events, preconfigured to work in various standard situations.

Enabling / Disabling an Email Event

Now let’s see how you can enable or disable an email event.

1 – Open the Mail Events menu, via System->Tools->Email->Events

2 – The grid containing the mail events will be loaded

Several pre-configured events are available, each event has a descriptive title, in the following form ‘Recipients of the notification – triggering event‘.

3 – Select a standard event, for example Requester – New Operation.

4 – This event sends an email notification to Requester User, at ticket creation.

To enable or disable an event, set the Status field as desired and save the event by clicking the Save or Apply buttons.

The meaning of the fields, the form of an event, is as follows:

FieldDescription
NameName of the event. Represents a descriptive field with which the events in the system will be displayed.
CodeEvent code. By convention it is a “normalization” of the Event Name, e.g.: “requester_user_new_operation”.
StatusThe status (enabled/disabled). If “Disabled” the event will not be active.
Send AttachmentsIf Yes will be sent all the attachments, of the record that triggers the event, evaluated as visible by the user with the most limited visibility among the recipients. For example, if the event concerns the notification of a new assignee in Service Operations, then the attachments of the newly updated Operations record will be sent as email attachments. Note: To learn more about configuring the visibility of attachments, see the Attachments Configuration section.
Email TemplateIt represents the template with which the emails related to the event will be sent.
ModelThe model of reference, that is the entity (ex: “DeepService – Operation” for tickets) to whose saving the email event must be executed.
Event ExpressionPHP code that identifies the condition. Through this scripting area, it is defined whether to send the email notification, based on the value of the template fields.
AScripting area in which, through PHP code, email addresses are added in the To field.
CcScripting area in which, through PHP code, email addresses are added in the Cc field.
CcnScripting area in which, through PHP code, email addresses are added in the Bcc field.
Custom CodePHP code executed after sending the email.

Custom Email Events Creation

In Deepser you can define and use custom email events in addition to the many standard events already defined in the system.

To create a new email event we can proceed in two ways: create it from scratch, or duplicate an existing one.

EMAIL EVENT CREATION

To create a new event from scratch, from the email event grid in the àEvent Email Toolsà àSystem section click on the ‘+ Create Event‘ button at the top right.

EMAIL EVENT DUPLICATION

Duplicating an event allows you to create a new event that will be the exact copy of the starting event, so that you can take full or partial advantage of its configuration.

The only differences will be the Name and the Code to which the suffixes “(copy)” and “_copy” will be added respectively.

To duplicate an already existing event, from its configuration form, click on the “Duplicate Event” button in the top right corner.

Custom Email Events Configuration

You can configure a new custom event, or modify an existing one.

Once you have filled the event form fields containing the main informations, generally contained in the “Main Data” Field Set, select the model (entity) for which to send the notification.

To enter the PHP code to configure the “Event Expression” and the notification recipients, expand the related scripting areas by clicking button with the “</> ” icon.

From the scripting areas, you can use the syntax $this->getModel() to access the instance of the selected model.

If the model is DeepActictivity – Activity, because you are creating or modifying an event for the notification when a commenti s added, with $this->getModel() you will access to the comment instance, not to the associated operation.

To access the related operation instance, use $this->getModel()->loadModelInstance().

Note: It is not possible to change the system email events configuration, in this case you need to duplicate the system email event and modify the duplicate.

EXAMPLE: CONFIGURE NOTIFICATION TO MANAGER GROUP FOR TICKETS WITH CRITICAL PRIORITY ASSIGNED TO THE FIRST LEVEL.

In this example we want to configure a notification event to send an email to “IT Managers” group if a ticket with “Critical” priority is created and assigned to the “IT First Level” group.

After defining the template and all the main event data follow these two steps.

STEP 1: “EVENT EXPRESSION” CONFIGURATION

The code in this field expresses the conditions for which a notification must be sent, in this case: “if a ticket with Critical priority is created and assigned to the IT First Level group“.

The following PHP code was used to express the condition:

				
					// Retreive the operation object
$operation = $this->getModel();
// The IT First Level group entity_id
$itFirstLevelGroupId = 10;
// Check if Operation new and Assigned Group is defined and it's exactly IT Frist Level
if($operation->isObjectNew() &&
    $operation->getAssignedGroupId() &&
    $operation->getAssignedGroupId() == $itFirstLevelGroupId){
    // "Critical" list value key
    $criticalPriorityId = 1;
    // If Operation has Critical priority then send the email notification
    if($operation->getPriorityId() == $criticalPriorityId){
        return true;
    }
}
return false;
				
			

STEP 2: RECIPIENTS CONFIGURATION

To, Cc, Bcc fils are used to define to whom the notification should be sent, in this case: “to the IT Managers group“.

To set the recipients of the notification, the following PHP code has been inserted in the ‘To‘ field.

				
					// The IT Managers group entity_id
$itManagerGroupId = 28;
// Load the IT Managers group object instance
$itManagerGroup = Deep::getModel('deep_group/group')->load($itManagerGroupId);
// Set message locale
$this->changeLanguage('en_US');
// If IT Managers group has its own email address (ex: mailing list)
if ($itManagerGroup->getEmail()) {
    // Send email to its email address
    $this->addTo($itManagerGroup->getEmail());
}
// Else send email to every user of the group
else {
    // Load all users in IT Managers group
    $managers = $itManagerGroup->loadUsers();
    // Iterate over the collection and set the email address of each manager as recipient
    foreach ($managers as $manager){
        $this->addTo($manager->getEmail());
    }
}
				
			

EXAMPLE 2: CONFIGURATION FOR SENDING NOTIFICATION TO CC INDICATED IN THE TICKET

In this example we want to modify the configuration of a notification event to the Requester User, to send the email by adding in Cc also the additional recipients indicated through a custom field in the operation.

Notification will be sent if the comment is visible to end users.

STEP 1: CREATE ADDITIONAL RECIPIENTS CUSTOM FIELD

Create a custom field in the DeepService – Operation model:

  • Column Name: cust_additional_recipients
  • Label: Additional Recipients
  • Column Type: Don’t create DB column
  • Element Type: Userassociation

Once you have created the custom field you need to add it to a formtemplate to start using it.

STEP 2: “CC” CONFIGURATION

In the Cc field all the users, associated to the operation through the custom field created in step1, are retreived and will be added in Cc to the notification email.

To set the additional recipients, use the following PHP code in the ‘Cc’ field.

You can configure a new custom event, or modify an existing one.

Once you have filled the event form fields containing the main informations, generally contained in the “Main Data” Field Set, select the model (entity) for which to send the notification.

To enter the PHP code to configure the “Event Expression” and the notification recipients, expand the related scripting areas by clicking button with the “</> ” icon.

From the scripting areas, you can use the syntax $this->getModel() to access the instance of the selected model.

If the model is DeepActictivity – Activity, because you are creating or modifying an event for the notification when a comment is added, with $this->getModel() you will access to the comment instance, not to the associated operation.

To access the related operation instance, use $this->getModel()->loadModelInstance().

				
					//REGISTERED CC
$additionalRecipient = $this->getModel()->loadModelInstance()->loadUserAssociations();
if ($additionalRecipient && is_array($additionalRecipient) && count($additionalRecipient) > 0){
    foreach ($additionalRecipient as $ccUserType){
            foreach ($ccUserType as $ccUsername){
                $ccUser = Deep::getModel('deep_admin/user')->loadByUsername($ccUsername);
                $this->addCc($ccUser->getEmail());
            }
    }
}
				
			

Also, use the following PHP code in the ‘Cc’ field to notify unregistered CC users.

				
					//UNREGISTERED CC
$additionalUnregisteredRecipient = $this->getModel()->loadModelInstance()-> getCustOperationCcUnregistered();
if ($additionalUnregisteredRecipient){
    $additionalUnregisteredRecipientArray = explode(';',$additionalUnregisteredRecipient);
    if(is_array($additionalUnregisteredRecipientArray) && count($additionalUnregisteredRecipientArray) >0){
        foreach ($additionalUnregisteredRecipientArray as $ccUnregisterdUser){
            $this->addCc(trim($ccUnregisterdUser));
        }
    }
}
				
			

Attach Report to Email Notification

You can attach a document, generated by a report already defined in Deepser, to a notification email.

This functionality is configured within Email Events.

EXAMPLE: ATTACH WORKLOG REPORT TO OPERATION CLOSURE NOTIFICATION.

To generate a report and attach it to an email notification you need to edit ‘To’ field of the email event.

In this example the configuration of the REQUESTER – Closed Operation event will be changed.

Replace the PHP code in the field ‘To‘ with the following one.

				
					//set Requester User as recipient
$user = $this->getModel()->getRequesterUser();
if ($user && $user->getId()){
    $this->changeLanguage($user->getLocale());
    $this->addTo($user->getEmail());
}
 
$attachment = Deep::getModel('deep_attachment/attachment');
//load the report instance
$report = Deep::getModel('deep_report/report')->load(14); // id 14 = Worklog Report
//pass to the report the id of the operation
$report->setFormData(['operation_id' => $this->getModel()->getId()]);
//run the report
$reportHistory = $report->run();
//set document as attachment
$attachment->setContent($reportHistory->getContent());
//define naming template
$attachment->setFileName('Worklog Report_'. $this->getModel()->getId() . '.pdf');
//set filetype
$attachment->setFileType(Zend_Mime::TYPE_OCTETSTREAM);
//add attachment to the message
$mailAttachments = new Varien_Data_Collection();
$mailAttachments->addItem($attachment);
$this->getMailbox()->setForcedAttachments($mailAttachments);
				
			

Email Templates

An Email Template defines layout and data of an email sent by Deepser.

Each email event is associated with a template.

By clicking the Preview button, on the top right corner in the email events form, it is possible to get a preview on how the notification email will appear.

By clicking the button you will be asked for the ID of the model for which you want to compile the template.

At this point the template will be displayed.

Email Template Configuration

To define a new Template, go to the System > Tools > Email > Templates menu andclick on button “Add Mail Template” in the top right corner.

The Fields of the form have the following meaning:

FIELDMEANING
CodeUnique code for the template, useful to insert the template in other templates.
NameThe name of the template, it will be displayed in the select-boxes.
StatusIf Disabled the template cannot be used.
SubjectThe phtml code for building the email subject line. Note: it is important that the subject of the email include Prefix of the mailbox and the id of the model (ex: “TICKET#101”) so, in case of reply, the model will be updated.
BodyPhtml code to compose the body of the email.
StylesCSS styles added to the body of the email

Typically, we define a set of templates and we can inlude the templates inside other templates.

This is useful in the case of header or footer for emails. You define the header with the company logo only once and then this is included in all other templates.

One more thing to pay attention to, when setting up a new template with links to display entities in Deepser, is which area they refer to.

A service operation, for example, can be displayed:

  • In Deepser Backend then to Admin, Agent and Key-User
  • In User Portal to any registered user if he is the requester or a requester supervisor
  • In Guest Portal to anyone who has appropriate link

The Url is different for each of the three areas.

New operation notification template for Requester User

In the following example,  we are going to configure an email template.

This template will be used to notify the Requester about the creation of a new operation.

STEP 1 – TEMPLATE IDENTIFICATION FIELDS

Fill in the template identificative fields:

  • Name (ex: ‘REQUESTER – OPERATION Created’)
  • Code (ex: ’email_to_requester_operation_created’)
  • Status: Enabled

STEP 2 – CONFIGURE THE EMAIL SUBJECT LINE

In the scripting area ‘Subject‘ insert the following PHP code

				
					<!--    Double underscore method check for available translations of the string passed as parameter -->
<!--   
        $this->getPrefix() retrieve the prefix setted in current outgoing mailbox configuration
        $this->getModel() returns the current model incance in this case the service operation instance
        $this->getModel()->getId() retrive the operation ID
-->
<?php echo Deep::helper('deep_email')->__('Ticket with ID')?>
 <?php echo $this->getPrefix().$this->getModel()->getId()?>
 <?php echo Deep::helper('deep_email')->__('sent')?>
				
			

The resulting subject will be like: “Ticket with ID TICKET#101 sent”.

STEP 3 – CONFIGURE THE EMAIL BODY

In the Body scripting area enter the following PHP code

				
					<?php
//$this->getModel() returns the current service operation instance
$operation = $this->getModel();
//$operation->getRequesterUser() loads the requester user object if he is registered
$requesterUser = $operation->getRequesterUser();
//test if requester is a registered user
$requesterIsRegistered = $requesterUser && $requesterUser->getId();
//if requester is registered then use getDisplayUsername() that returns 'Firstname Lastname'
//if the requester is not a registered user use the value of the service operation field requester_username
$requesterUsername = $requesterIsRegistered ? $requesterUser->getDisplayUsername() : $operation->getRequesterUsername();
?>
 
<!-- include header template -->
<?php $this->includeTemplate("header") ?>
 
<!-- Start of Main Content -->
<tr style="">
    <td bgcolor="#FFFFFF" align="center" style="">
        <table width="100%" align="center" cellpadding="0" cellspacing="0" border="0" class="devicewidth" style="">
            <tbody style="">
            <!-- Start Spacer -->
            <tr>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="h26" height="36" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- End Spacer -->
            <tr style="">
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="mktEditable content mktEditable content" id="edit_text_1" valign="middle"
                    style="font-family:Calibri, Helvetica, sans-serif; font-size:16px; color:#505050;
                        text-align:left; line-height:25.6px; font-weight:normal; text-transform:none;">
                    <p>
                        <br>
                        <?php echo Deep::helper('deep_email')->__('Dear') . ' ' . $requesterUsername ?>,
                        <br>
                         
                        <?php $url = $operation->getPortalUrl() ?>
                        <?php echo Deep::helper('deep_email')->__('Ticket with ID')?>
                        <b style="font-weight: 700;">
                            <?php if($requesterIsRegistered):?>  
                                <a href="<?php echo $url ?>"><?php echo $operation->getId()?></a>
                            <?php else:?>
                                <?php echo $operation->getId()?>
                            <?php endif;?>  
                        </b> <?php echo Deep::helper('deep_email')->__('has been received by our support')?>
                        <br><br>
                         
                        <strong><?php echo Deep::helper('deep_email')->__('Title')?></strong>:
                        <br>
                        <!-- print the operation Title -->
                        <?php echo $operation->getTitle()?>
                        <br><br>
                         
                         
                        <strong><?php echo Deep::helper('deep_email')->__('Description')?></strong>:
                        <br>
                        <!-- print the operation Description -->
                        <?php echo $operation->getDescription()?>
                        <br>
                         
                        <!-- Requester -->
                        <strong><?php echo Deep::helper('deep_service')->__('Requester User')?></strong>:
                        <?php if($requesterIsRegistered):?>
                            <?php if($requesterUser->getAvatar()):?>
                                <br>
                                <!-- if user is regitered and has an avatar print it -->
                                <img src="<?php echo $requesterUser->getAvatarUrl() ?>" border="0"
                                    style="-ms-interpolation-mode: bicubic;" width="16" />
                               <?php endif;?>
                        <?php endif;?>
                        &nbsp;&nbsp;&nbsp;
                        <!-- print the requester username -->
                        <?php echo $requesterUsername ?>
                        <br><br>
 
                        <!-- Urgency -->
                        <?php if($operation->getUrgencyId()):?>
                        <strong><?php echo Deep::helper('deep_email')->__('Urgency')?></strong>:
                            <?php
                            //load service operation urgency list
                            $urgencyList = Deep::helper('deep_list')->loadList(
                                Deep_Service_Model_Operation::LIST_CODE_URGENCY
                                );
                            //get the corrisponding Urgency label
                            $urgencyValue = $urgencyList->getValue($operation->getUrgencyId()); ?>
                            <br>
                            <!-- print urgency label -->
                            <?php echo Deep::helper('deep_email')->__($urgencyValue->getValueLabel()); ?>
                        <?php endif;?>
                        <br><br>
                    </p>
                </td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- Start Spacer -->
            <tr>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td height="30" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- End Spacer -->
            </tbody>
        </table>
    </td>
</tr>
<!-- End of Main Content -->
 
<?php if($requesterIsRegistered):?>
    <!-- start of Button -->
    <tr style="">
        <td bgcolor="#FFFFFF" align="center" class="mktEditable" id="edit_cta_button" style="">
            <table width="100%" border="0" cellspacing="0" cellpadding="0">
                <tbody>
                <tr>
                    <td class="w22" width="41" style="font-size: 1px; line-height: 1px;">&nbsp;</td>
                    <td align="left">
                        <table class="button" cellpadding="0" cellspacing="0" border="0" align="left"
                            bgcolor="#0080ff" style="-webkit-border-radius: 4px;
                                -moz-border-radius: 4px; border-radius: 4px;">
                            <tbody>
                            <tr>
                                <td width="518" align="center" valign="middle" height="65">
                                    <span style="color: #ffffff; text-decoration: none;">
                                        <!-- set the operation link as button link -->
                                        <a class="mobButton mktNoTok" href="<?php echo $url ?>"
                                            style="font-family: Calibri, Helvetica, sans-serif;
                                                font-size: 16px; color: #ffffff; display: block; height: 65px;
                                                    mso-line-height-rule: exactly; line-height: 65px;
                                                        font-weight: normal; text-decoration: none;
                                                            text-align: center!important;"
                                                                target="_blank" title="Link al ticket">
                                            <?php echo Deep::helper('deep_email')->__('Go to the Ticket')?>
                                        </a>
                                    </span>
                                </td>
                            </tr>
                            </tbody>
                        </table>
                    </td>
                    <td class="w22" width="41" style="font-size: 1px; line-height: 1px;">&nbsp;</td>
                </tr>
                </tbody>
            </table>
        </td>
    </tr>
    <!-- end of Button -->
<?php endif;?>
 
<!-- include footer template -->
<?php $this->includeTemplate("footer") ?>
				
			

The email notification body will look like the image below.

New or Updated comment notification template for Requester

In the following example, we are going to configure an email template to notify a user that a comment has been added or updated where he is  the Requester.

STEP 1 – TEMPLATE IDENTIFICATION FIELDS

As a first step, fill in the template identificative fields:

  • Name (es: ‘REQUESTER – Comment Created or Updated ’)
  • Code (es: ‘operation_comment_created_updated_requester’)
  • Status: Enabled

STEP 2 – CONFIGURE THE EMAIL SUBJECT LINE

In the scripting area ‘Subject‘ insert the following PHP code

				
					<!--
    $this->getModel() returns the current model incance in this case the activity instance
    $this->getModel()->isObjectNew() returns true if object is new
    if object is new print "New Comment" else Comment Updated
    __ method (double underscore) check for available translations of the string passed as parameter
-->
<?php if ($this->getModel()->isObjectNew()) : ?>
    <?php echo Deep::helper('deep_email')->__('New Comment')?>
<?php else: ?>
    <?php echo Deep::helper('deep_email')->__('Comment Updated')?>
<?php endif; ?>
 <?php echo Deep::helper('deep_email')->__('for Ticket ID')?>
<!--   
    $this->getPrefix() retrieve the prefix setted in current outgoing mailbox configuration
    $this->getModel()->getModelId() retrive the main model ID to which the activity is associated
        in this case the operation ID
-->
 <?php echo $this->getPrefix() ?><?php echo $this->getModel()->getModelId() ?>
				
			

The resulting subject will look like: “New Comment for Ticket ID TICKET#101” or “Comment Updated for Ticket ID TICKET#”.

STEP 3 – CONFIGURE THE EMAIL BODY

In the Body scripting area enter the following PHP code

				
					<?php
//$this->getModel() returns the main model oject instance, in this case Activity
$activity = $this->getModel();
//retreive user who created comment
$createdByUser = $activity->getCreatedBy() ?
    Deep::getModel('deep_admin/user')->loadByUsername($activity->getCreatedBy()) : null;
//determine createdby user display username
$createdByDisplayUsername = $createdByUser && $createdByUser->getId() ?
    $createdByUser->getDisplayUsername() : $activity->getCreatedBy();
//$activity->loadModelInstance() returns main model instance in this case operation object instance
$operation = $activity->loadModelInstance();
//getAssignedUser() returns assigned user object instance
$assignedUser = $operation ? $operation->getAssignedUser() : null;
//getDisplayUsername() returns "First Lastname" string
$assignedUsername = $assignedUser && $assignedUser->getId() ? $assignedUser->getDisplayUsername() : null;
//$operation->getRequesterUser() loads the requester user object if he is registered
$requesterUser = $operation ? $operation->getRequesterUser() : null;
//test if requester is a registered user
$requesterIsRegistered = $requesterUser && $requesterUser->getId();
//if requester is registered then use getDisplayUsername() that returns 'Firstname Lastname'
//if the requester is not a registered user use the value of the service operation field requester_username
$requesterUsername = $requesterIsRegistered ? $requesterUser->getDisplayUsername() : $operation->getRequesterUsername();
?>
 
<!-- include header template -->
<?php $this->includeTemplate("header") ?>
<!-- Start of Main Content -->
<tr style="">
    <td bgcolor="#FFFFFF" align="center" style="">
        <table width="100%" align="center" cellpadding="0" cellspacing="0" border="0" class="devicewidth"
            style="">
            <tbody style="">
            <!-- Start Spacer -->
            <tr>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="h26" height="36" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- End Spacer -->
            <tr style="">
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="mktEditable content mktEditable content" id="edit_text_1" valign="middle"
                    style="font-family:Calibri, Helvetica, sans-serif; font-size:16px; color:#505050;
                    text-align:left; line-height:25.6px; font-weight:normal; text-transform:none;">
                    <p>
                        <br>
                        <?php echo Deep::helper('deep_email')->__('Dear') .' ' . $requesterUsername ?>,
                        <br>
 
                        <?php echo Deep::helper('deep_email')->__('A Comment has been') .' ' ?>
                        <b>
                        <?php if ($activity->isObjectNew()) : ?>
                            <?php echo Deep::helper('deep_email')->__('created') . ' '?>
                        <?php else: ?>
                            <?php echo Deep::helper('deep_email')->__('updated') . ' '?>
                        <?php endif; ?>
                        </b>
                        <?php echo Deep::helper('deep_email')->__('for Ticket ID') ?>:
                        <b style="font-weight: 700;">
                            <?php if($requesterIsRegistered):?>
                                <?php $url = $operation->getPortalUrl() ?>
                                <a href="<?php echo $url ?>">
                                    <?php echo $operation->getId()?>
                                </a>
                            <?php else:?>
                                <?php echo $operation->getId()?>
                            <?php endif;?>
                        </b>
                        <br><br>
 
                        <!-- Ticket Title -->
                        <strong><?php echo Deep::helper('deep_email')->__('Ticket Title')?></strong>:
                        <br>
                        <!-- print the operation Title -->
                        <?php echo $operation->getTitle()?>
                        <br><br><br>
 
                        <!-- Activity Description -->
                        <strong><?php echo Deep::helper('deep_email')->__('Comment')?></strong>:
                        <!-- print the activtity Description -->
                        <br><?php echo $activity->getDescription()?>
                        <br>
 
                        <!-- Created by -->
                        <strong><?php echo Deep::helper('deep_service')
                            ->__('User who created the Comment')?></strong>:
                        <?php if($createdByUser && $createdByUser->getId()):?>
                       <?php if($createdByUser->getAvatar()):?>
                           <br>
                           <!-- if created by user is regitered and has an avatar print it -->
                           <img src="<?php echo $createdByUser->getAvatarUrl() ?>" border="0"
                               style="-ms-interpolation-mode: bicubic;" width="16" />
                            <?php endif;?>
                        <?php endif;?>
                        <!-- print created by username or displayusername -->
                        &nbsp;&nbsp;&nbsp;<?php echo $createdByDisplayUsername ?>
                        <br><br>
                    </p>
                </td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- Start Spacer -->
            <tr>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td height="30" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- End Spacer -->
            </tbody>
        </table>
    </td>
</tr>
<!-- End of Main Content -->
 
<?php if($requesterIsRegistered):?>
<!-- start of Button -->
<tr style="">
    <td bgcolor="#FFFFFF" align="center" class="mktEditable" id="edit_cta_button" style="">
        <table width="100%" border="0" cellspacing="0" cellpadding="0">
            <tbody>
            <tr>
                <td class="w22" width="41" style="font-size: 1px; line-height: 1px;">&nbsp;</td>
                <td align="left">
                    <table class="button" cellpadding="0" cellspacing="0" border="0" align="left"
                        bgcolor="#0080ff" style="-webkit-border-radius: 4px; -moz-border-radius: 4px;
                        border-radius: 4px;">
                        <tbody>
                        <tr>
                            <td width="518" align="center" valign="middle" height="65">
                                <span style="color: #ffffff; text-decoration: none;">
                                    <!-- set the operation link as button link -->
                                    <a class="mobButton mktNoTok" href="<?php echo $url ?>"
                                        style="font-family: Calibri, Helvetica, sans-serif; font-size: 16px;
                                        color: #ffffff; display: block; height: 65px;
                                        mso-line-height-rule: exactly; line-height: 65px;
                                        font-weight: normal; text-decoration: none;
                                        text-align: center!important;" target="_blank"
                                        title="Link to the ticket">
                                        <?php echo Deep::helper('deep_email')->__('Go to the Ticket')?>
                                    </a>
                        </span>
                            </td>
                        </tr>
                        </tbody>
                    </table>
                   </td>
                <td class="w22" width="41" style="font-size: 1px; line-height: 1px;">&nbsp;</td>
            </tr>
            </tbody>
        </table>
    </td>
</tr>
<!-- end of Button -->
<?php endif;?>
 
<!-- include footer template -->
<?php $this->includeTemplate("footer") ?>
				
			

The notification email body will look like the image below.

Email Webclient

Deepser has an integrated email webclient that allows users to send and manage emails directly from within the platform, facilitating communication and centralized management of company information.

EMAIL WEBCLIENT CONFIGURATION

First of all, to activate the possibility of sending via email webclient it is necessary to configure an outgoing mailbox.

Once done, it will be necessary to enable the possibility of using the mailbox for sending via email webclient.

In particular, from the “System Data” section it will be possible to configure the “Webclient Group” and “Webclient Model Alias” fields:

Both fields must always be valued so that the mailbox can be used to send emails.

Specifically:

FIELD

DESCRIPTION

Webclient Group

With this field you can enable using of the email webclient to a specific group (or to all groups).

Webclient Model Alias

With this field you can enable using of the email webclient into a specific model.

EMAIL WEBCLIENT USING FROM MODEL

The use of the email webclient, as can be guessed from the type of configuration, can therefore be used within a single model (based on the configuration of the mailboxes).

Specifically, there must be an “Emailwriter” type field within the template.

By doing so, it will be possible to invoke the email webclient to send an email directly from within a record. Below is an example of an “Emailwriter” field on the Operations template:

By clicking on the button in question, the webclient email screen will open:

Through this screen it will then be possible to compose the email and send it by clicking on the “Send” button at the top right of the screen.

Below are the details of the fields present and their use:

FIELD

DESCRIPTION

From

In this field, you can select the mailbox you want to use.

In this case you can select only the mailboxes configured to be used with email webclient.

Display Name

This field is pre-populated according to the selected mailbox. However, it can be modified to use a different display name for the email you are sending.

To

email recipient field through which you can select users or groups already registered on Deepser or enter new email addresses.

Cc

recipient field in copy of the email through which it is possible to select users or groups already registered on Deepser or enter new email addresses.

Bcc

Recipient field in blind copy of the email through which it is possible to select users or groups already registered on Deepser or enter new email addresses.

Subject

Subject of the email

Body Html

Message body

Attachments

Attachments

Create Comments

A field that, if set to “yes”, allows you to upload the email as a comment in the record to which it belongs.

Once sent, in this case, the email will be linked to the same record from which it was sent via webclient email:

GENERAL USING OF EMAIL WEBCLIENT

By clicking on the “@” icon at the top right of the Deepser screen, you can access a sub-menu that allows you to send emails or view emails sent via email webclient.

By clicking on “Write”, you will see the same email sending screen presented previously:

By accessing instead through “List” you will have the complete list of all the emails sent through this mode.

Now, a brief explanation of the buttons displayed in the grid (Webclient Messages) of sent emails:

  1. Allows you to view the email.
  2. The Ingoing Email icon box.
  3. The Outgoing Email icon box.
  4. Message not sent icon.
  5. Allows you to resend the ermail.
  6. Reply to the email.
  7. Answer to everyone.
  8.  Forward

Multi Factor

Multi-factor authentication (MFA) is a security system that requires multiple forms of verification to authenticate a user’s identity and grant access to a system. Instead of relying solely on a password, MFA typically combines something the user knows (like a password) with something they have (such as a smartphone or email address for receiving a code).This layered approach significantly enhances security by making it harder for unauthorized users to gain access, even if they obtain one factor of authentication.

Multi Factor Configuration

To go to the Multi Factor Configuration you will need to go to the

System->Tools->Multi Factor->Configuration

To create a new one you will need to Click on Add Configuration button on the top right of the screen.

The following screen will open:

Field Name

Description

Name

Name of the Configuration

Type

Type of the Multi Factor Authentication TOTP(APP) or Email

Enable Groups

Groups that will be able to use Multi Factor Authentication

Label

Configuration’s Label that will be shown on the app

Status

Enabled or Disabled. Weather the session is enabled or disabled.

Note: Both types of Multi Factor Authentication are suggested to be enabled in order to deal with unforeseen events(such as phone out of charge or unable to access email).

Enabling Email MFA in Deepser

Email MFA(Multi Factor Authentication) is possible in Deepser. In order to enable it you will have to choose the type Email in the Multi Factor Configuration.

Field Name

Description

Name

Name of the Configuration

Type

Type of the Multi Factor Authentication TOTP(APP) or Email

Enable Groups

Groups that will be able to use Multi Factor Authentication

Status

Enabled or Disabled. Weather the session is enabled or disabled.

Mailbox

The configured mailbox that will be used to send out the code via email

Mail Template

The email template that will be received via email

Token Valid Time

The time that the received code is valid for

After all of the fields are completed, whenever you try to log in the code will be sent to the email of the account.

Now every time you try to log in you will have to enter the MFA code received via email.

Depending on how you have configured the email template, this is how it will look like on the email.

In case you fail to insert the code within the chosen Token Valid Time, the following screen will appear which notifies you.

Useful guides: Out-going mailbox , Email Templates , OAuth Client for Email Integration

Enabling APP MFA in Deepser

In order to activate the MFA in deepser you will need to go to your account settings.

Afterwards you will need to go the Security tab.

To enhance security, Deepser utilizes multi-factor authentication (MFA), which integrates an additional verification step involving a secondary device, typically a mobile phone.

You can verify your identity using an authenticator app like Authy, Google Authenticator, Microsoft Authenticator. For this guide, we are going to use Authy.

Scan this QR code through the app; it will display a 6 digits code which you need to enter below to enable login by app.

Using Authy App, you will have to Add An Account and then scan the QR code shown on account settings of deepser.

After you have scanned it, you would be able to see the configuration settings you set before, which you can also change whenever you need to from deepser or through the app.

After you have saved the settings, the 6 digit code will appear on your mobile screen, which you are required to enter in the Account Security Field.

And after the correct code has been set, you have to click on Verify and the following screen will appear:

Now every time you try to log in you will have to enter the MFA code in the authentication app.

Please note that each verification code generated for Deepser’s multi-factor authentication (MFA) remains valid for 30 seconds, after which a new code is automatically generated.

Authentication Request

Each request for log in is stored and saved in Deepser. You can view it by heading to

 System->Tools->Multi Factor->Authentication Request.

Field Name

Description

User

The user that requested to log in

Session ID

Unique ID for each log in session

State

Shows if the log in was verified or not

Generated At

The date and time the request was generated

Attempts

How many times did it take for the user to set the correct authentication code

Last Attempt At

Date and Time the user last tried to log in

Last User Agent

Web Browser or Application that was most recently used to access Deepser

Last IP Address

Numerical Label of the most recent device network that was used to access Deepser

Status

Enabled or Disabled. Weather the session is enabled or disabled.

Escalation

Escalation rules in Deepser are an important tool in Deepser’s entities management flow that allow you to perform time-based actions, e.g. modify the status, send an email or create/edit external entities based on a metric.

Articles

  • Escalation rule levels
  • Configuring Escalation Rules
  • Configure an escalation rule that modifies entity.
  • Escalation rule that sends an email notification
  • Create an escalation rule that is based on a metric
  • Configure an escalation rule that generates other entities

Escalation rule levels

In Deepser, all entities that can be processed by escalation rules have a “Level” attribute that serves as a filter to indicate which escalation rules should be evaluated on that entity.

Escalation rules process only entities whose level is equal to the “Level” attribute set in the rule itself or lower, after their execution they set the “Level” attribute of the processed entity to the  value indicated in the “Next Level” field of the rule.  

This mechanism allows you to make a skimming on the rules that will have to be evaluated for each entity, allowing you to define rules that must be evaluated only once for each entity of the selected type.

RULES THAT RUN ONLY 1 TIME PER ENTITY

To configure an escalation rule to run only once, it will be sufficient to configure the “Level” field of the escalation rules to the desired level (by default 0) and the  “Next Level” field of the rule to a value  higher than that of the  “Level” field for example to 1 in the case of default.

RULES THAT RUN MULTIPLE TIMES PER ENTITY

To make sure  that an escalation rule is executed potentially several times on the same entity, it will be sufficient to set the “Level” field and the “Next Level” field to the same value.

This will cause the rule to evaluate that ticket potentially several times  (at  most 1 per execution of the rule itself), if the “Level” of those entities were changed by  other rules, the behavior of the rule that we are configuring may not be what was expected.

For this reason, the advice we give is always to evaluate the rules as a whole to understand if one or more rules can conflict  (intentionally or not).

COMPETITION FROM ESCALATION RULES

Suppose the existence of 2 escalation rules: “A” and “B”, the “A” rule takes charge of all tickets that have not been assigned  for  more than two hours and sends an email notification  (the implementation of these types of  rules will be covered in subsequent lessons), setting the “Level” field of the processed entity  to 0 from 0.

Rule B instead takes charge of all tickets that have not been assigned for more than 4 hours and sends an email also setting the priority to “Critical” and changing the level of the entity to 1.

In this case, if a ticket’s  processed by rule “B”,  which includes more general conditions, it is intended not to be processed by rule A.

In general, however, it is necessary to pay attention to the escalation rules as a whole.

Configuring Escalation Rules

To configure a new Escalation rule in Deepser You will need to go to the System -> Service Configuration -> Escalation Rule menu.

Here, you will need to click on the “Add Rule” button.

Now the following screen will open:

Below are the fields and their meaning:

FieldDescription
NameName of the escalation rule
Model AliasModel on which it will apply
Email EventAssociated email event that will be launched if the conditions of the rule are true
LevelLevel, this field indicates what is the level of tickets that will have to be processed, by default it is 0 for all tickets
Next LevelThe new level that the ticket will have after being processed by the rule
Cron ExpressionExpression Cron, indicates how often this rule will be processed.
StatusStatus of the rule, if “Enabled” the rule will be evaluated otherwise no.

Note that the conditions to be specified for the rule will appear only after the rule has been saved at least once.

At this point, click on “Save” or “Apply” to save the rule.

At the end, the following screen will appear:

The new fields that will appear are the following:

FieldDescription
Escalate all Records with following values (Main Filter)This query builder will be used to filter the tickets that will have to be processed In order to be evaluated , tickets must comply with the conditions of the query builder
Expression Input (Script)This script field will be used to filter tickets that will have to be processed. In order to be processed, tickets must comply with the conditions of the script field (must return true).
Escalate all Records with following Timer values (applied after the Main Filter)This query builder will be used to filter tickets that will have to be processed. In order to be processed, tickets must comply with the conditions of the query builder, in addition in this case the SLA metrics will also be evaluated as parameters of the query builder.
Expression Timer (Script)This script field will be used to filter the tickets that will have to be processed . In order to be evaluated tickets must comply with the conditions of the script field in addition in this case the metrics of the SLA will be evaluated as parameters of the query builder.
Set Records values toThis query builder is used to set the values  that have to be modified in the processed record.
Expression Output (Script)This scripting field is used to set the values that have to be modified in the processed record.

As a last step, after filling in the desired fields, you will need to click on the “Save” or “Apply” button to save the rule.

Configure an escalation rule that modifies entity.

Suppose you want to configure an escalation rule that gives high priority to all tickets whose requesting company is “Acme International”.

To do this, you will need to go to the System -> Service Configuration -> Escalation Rule menu.

Here, you will need to click on the “Add Rule” button.

Now the following screen will open:

At this point, we configure the “Name” field as “High Priority Acme International”.

We set the field “Model Alias” to “DeepService – Operation”.

Now, we configure the Level to zero and Next Level to1 fields, that is, this rule will process all tickets in zero state only once.

At this moment, we set the field “Cron Expression”: every 5 minutes using the drop-down menu located under the field itself.

As the last step of this first phase, click on “Save” or “Apply” to save the rule.

CONFIGURING QUERY BUILDERS

Now configure in the newly created rule the query builder “Escalate all Records with following values (Main Filter)” like this:

Now, let’s set in the newly created rule the query builder “Set Records values to” like this:

Finally, we can click on “Save” or “Apply”.

Escalation rule that sends an email notification

In Deepser, Escalation rules can trigger email notifications. This allows you to use escalation rules to eliminate alerts   when specific events occur. In the following example, we are going to create an escalation rule that will notify the user  in case  the requesting company is Acme International. In this example, we will also use the escalation rule created  in the previous example.

E-MAIL TEMPLATE CREATION

In order to send the email notification to the assignee user, it will be necessary to create an email event with its associated mail template that will be used by Deepser to send the email from the escalation rule. To create a custom, you will need to go to the System -> Tools -> Email -> Template menu. Then you will need to click on the”Add  Mail Template” button. In the screen that will open you will need to define a name for the template, to do this, simply enter the desired name in the “Name” field. Next we will define a code for the template, filling in the “Code” field. At this point, it will be possible to insert in the”Subject”section the php code that will compose the subject of the email. You can use the following code as a reference to compose the subject of the email:

				
					<?php echo Deep::helper('deep_email')->__('DEEPSER – New ticket from Acme International')?>
				
			

Now, it will be possible to insert in the “Body” section, which will represent the content of the message, the PHP / HTML code that will be used to generate the body of the mail.

You can use the following code as a reference when creating the body:

				
					<?php

$requesterUser = $this->getModel()->getRequesterUser();

$assignedUser = $this->getModel()->getAssignedUser();

?>

<?php $this->includeTemplate(“header”) ?>

<!– Start of Main Content –>

<tr style=””>

    <td bgcolor=”#FFFFFF” align=”center” style=””>

        <table width=”100%” align=”center” cellpadding=”0″ cellspacing=”0″ bor-der=”0″ class=”devicewidth” style=””>

            <tbody style=””>

            <!– Start Spacer –>

            <tr>

                <td class=”w22″ width=”41″ style=”font-size:1px; line-height:1px;”>&nbsp;</td>

                <td class=”h26″ height=”36″ style=”font-size:1px; line-height:1px;”>&nbsp;</td>

                <td class=”w22″ width=”41″ style=”font-size:1px; line-height:1px;”>&nbsp;</td>

            </tr>

            <!– End Spacer –>

            <tr style=””>

                <td class=”w22″ width=”41″ style=”font-size:1px; line-height:1px;”>&nbsp;</td>

                <td class=”mktEditable content mktEditable content” id=”edit_text_1″ valign=”middle” style=”font-family:Calibri, Helvetica, sans-serif; font-size:16px; color:#505050; text-align:left; line-height:25.6px; font-weight:normal; text-transform:none;”>

                    <p>

                        <br>

                        <?php echo Deep::helper(‘deep_email’)->__(‘Dear %s’, $this->getModel()->getAssignedUser()->getDisplayUsername())?>,<br>

                        <?php $url = $this->getModel()->getAssignedUser()->isUser() ? $this->getModel()->getPortalUrl() : $this->getModel()->getUrl(); ?>

                        <?php echo Deep::helper(‘deep_email’)->__(‘You have Re-cived a new ticket from Acme International’)?> <b style=”font-weight: 700;”><a href=”<?php echo $url ?>”><?php echo $this->getModel()->getId()?></a></b>

                        <br>

                        <br>

                        <strong><?php echo Deep::helper(‘deep_email’)->__(‘Title’)?></strong>:

                        <br><?php echo $this->getModel()->getTitle()?><br><br>

                        <strong><?php echo Deep::helper(‘deep_email’)->__(‘Description’)?></strong>:

                        <br><?php echo $this->getModel()->getDescription()?><br>

                        <!– Status –>

                        <?php if($this->getModel()->getStatus()):?>

                        <strong><?php echo Deep::helper(‘deep_email’)->__(‘Status’)?></strong>:

                            <?php

                            $statusList = Deep::helper(‘deep_list’)->loadList(Deep_Service_Model_Operation::LIST_CODE_STATUS);

                            $statusValue = $statusList->getValue($this->getModel()->getStatus());

                            ?>

                            <br><?php echo Deep::helper(‘deep_email’)->__($statusValue->getValueLabel()); ?><br><br>

                        <?php endif;?>

                        <!– Requester –>

                        <?php if($requesterUser && $requesterUser->getId()):?>

                            <strong><?php echo Deep::helper(‘deep_service’)->__(‘Requester User’)?></strong>:

                            <?php if($this->getModel()->getRequesterUser()->getAvatar()):?>

                            <br><img src=”<?php echo $this->getModel()->getRequesterUser()->getAvatarUrl() ?>” border=”0″ style=”-ms-interpolation-mode: bicubic;” width=”16″ />

                            <?php endif;?>

                            &nbsp;&nbsp;&nbsp;<?php echo $this->getModel()->getRequesterUser()->getDisplayUsername() ?><br><br>

                        <?php endif;?>

                        <!– Assigned –>

                        <?php if($assignedUser && $assignedUser->getId()):?>

                        <strong><?php echo Deep::helper(‘deep_service’)->__(‘Assigned User’)?></strong>:

                            <?php if($this->getModel()->getAssignedUser()->getAvatar()):?>

                            <br><img src=”<?php echo $this->getModel()->getAssignedUser()->getAvatarUrl() ?>” border=”0″ style=”-ms-interpolation-mode: bicubic;” width=”16″ />

                            <?php endif;?>

                            &nbsp;&nbsp;&nbsp;<?php echo $this->getModel()->getAssignedUser()->getDisplayUsername() ?><br><br>

                        <?php endif;?>

                        <!– Urgency –>

                        <?php if($this->getModel()->getUrgencyId()):?>

                        <strong><?php echo Deep::helper(‘deep_email’)->__(‘Urgency’)?></strong>:

                            <?php

                            $urgencyList = Deep::helper(‘deep_list’)->loadList(Deep_Service_Model_Operation::LIST_CODE_URGENCY);

                            $urgencyValue = $urgencyList->getValue($this->getModel()->getUrgencyId());

                            ?>

                            <br><?php echo Deep::helper(‘deep_email’)->__($urgencyValue->getValueLabel()); ?><br><br>

                        <?php endif;?>

                        <!– Priority –>

                        <?php if($this->getModel()->getPriorityId()):?>

                        <strong><?php echo Deep::helper(‘deep_email’)->__(‘Priority’)?></strong>:

                            <?php

                            $priorityList = Deep::helper(‘deep_list’)->loadList(Deep_Service_Model_Operation::LIST_CODE_PRIORITY);

                            $priorityValue = $priorityList->getValue($this->getModel()->getPriorityId());

                            ?>

                            <br><?php echo Deep::helper(‘deep_email’)->__($priorityValue->getValueLabel()); ?><br><br>

                        <?php endif;?>

                        <!– Solution –>

                        <?php if($this->getModel()->getSolution()):?>

                        <strong><?php echo Deep::helper(‘deep_email’)->__(‘Solution’)?></strong>:

                        <br><?php echo $this->getModel()->getSolution()?>

                        <br>

                        <?php endif;?>

                    </p>

                </td>

                <td class=”w22″ width=”41″ style=”font-size:1px; line-height:1px;”>&nbsp;</td>

            </tr>

            <!– Start Spacer –>

            <tr>

                <td class=”w22″ width=”41″ style=”font-size:1px; line-height:1px;”>&nbsp;</td>

                <td height=”30″ style=”font-size:1px; line-height:1px;”>&nbsp;</td>

                <td class=”w22″ width=”41″ style=”font-size:1px; line-height:1px;”>&nbsp;</td>

            </tr>

            <!– End Spacer –>

            </tbody>

        </table>

    </td>

</tr>

<!– End of Main Content –>

<!– End of Main Content –>

<?php $url = $this->getModel()->getUrlByUser($assignedUser); ?>

<!– start of Button –>

<tr style=””>

    <td bgcolor=”#FFFFFF” align=”center” class=”mktEditable” id=”edit_cta_button” style=””>

        <table width=”100%” border=”0″ cellspacing=”0″ cellpadding=”0″>

            <tbody>

            <tr>

                <td class=”w22″ width=”41″ style=”font-size: 1px; line-height: 1px;”>&nbsp;</td>

                <td align=”left”>

                    <table class=”button” cellpadding=”0″ cellspacing=”0″ bor-der=”0″ align=”left” bgcolor=”#0080ff” style=”-webkit-border-radius: 4px; -moz-border-radius: 4px; border-radius: 4px;”>

                        <tbody>

                        <tr>

                            <td width=”518″ align=”center” valign=”middle” height=”65″>

                                <span style=”color: #ffffff; text-decoration: none;”>

                                        <a class=”mobButton mktNoTok” href=”<?php echo $url ?>” style=”font-family: Calibri, Helvetica, sans-serif; font-size: 16px; color: #ffffff; display: block; height: 65px; mso-line-height-rule: exactly; line-height: 65px; font-weight: normal; text-decoration: none; text-align: center!important;” target=”_blank” title=”Link al ticket”>

                                            <?php echo Deep::helper(‘deep_email’)->__(‘Go to the Ticket’)?>

                                        </a>

                                </span>

                            </td>

                        </tr>

                        </tbody>

                    </table> </td>

                <td class=”w22″ width=”41″ style=”font-size: 1px; line-height: 1px;”>&nbsp;</td>

            </tr>

            </tbody>

        </table>

    </td>

</tr>

<!– end of Button –>

<?php $this->includeTemplate(“footer”) ?>
				
			

And click on the “Save” or”Apply”button

EMAIL EVENT CREATION

To create a custom mail event you will need to go to the System -> Tools -> Email -> Event menu. At this point you will need to click on the”Add  Event” button. At this moment, it will be necessary to give a name to the event by filling in the “Name” field. We define Whether to send attachments by changing the value of the field”Send  Attachments” to “No”. Now in the “Email Template” field we select the template created in the previous point of this guide. In the “Event Trigger” section, select “DeepService – Operation” in the “Model” field In the “Event Expression”entry. We insert the following code:

				
					// if the Company is Acme International
if($this->getModel()->getData("requester_company_id") == Deep::getModel("deep_company/company")->load("ACME International",'name')->getId() ){
    if ($this->getModel()->getData('escalation_rule')){
         return true;
    }
}
return false;
				
			

In the “To” section We insert the following code:

				
					$user = $this->getModel()->getAssignedUser();
if ($user && $user->getId()){
    $this->changeLanguage($user->getLocale());
    $this->addTo($user->getEmail());
}
				
			

At this point, we can go to click the “Save” or “Apply” button Now the event will have been saved

ASSIGNING THE MAIL EVENT TO THE ESCALATION RULE

To assign the mail event to the escalation rule you will need to go to the menu: System ->  Service  Configuration. Here you will need to go to the previously created rule or any escalation rule you want to change. In the Escalation Rule screen you will need to select the Created event from the drop-down menu that will appear by clicking the “Email Event” field. At this point you will need to click the “Save” or”Apply” button.

EXAMPLE: SENDING EMAIL TO THE OPERATOR WHEN THE NUMBER OF HOURS IS LESS THAN 4

In this example, suppose you want to email the administrator when the number of hours remaining in a contract line is less than 4

E-MAIL TEMPLATE CREATION

In order to send the email notification to the administrator, it will be necessary to create an email event with its associated mail template that will be used by Deepser to send the email from the escalation rule. To create a custom mail event, you will need to go to the System -> Tools -> Email -> Template menu. Then you will need to click on the”Add  Mail Template” button. In the screen that will open you will need to define a name for the template, to do this, simply enter the desired name in the “Name” field. Next we will define a code for the template, filling in the “Code” field. At this point, it will be possible to insert in the”Subject”section the php code that will compose the subject of the email. You can use the following code as a reference to compose the subject of the email:

				
					<?php $line = $this->getModel()?>
The contract line <?php echo $line->getLineNumber() . ' - ' . $line->getName()?> of the contract <?php echo $line->loadContract()->getContractNumber() . ' - ' . $line->loadContract()->getName()?> is going low
				
			

Now it will be possible to insert in the “Body” section, which will represent the content of the message, the PHP / HTML code that will be used to generate the body of the mail. You can use the following code as a reference when creating the body:

				
					<?php $this->includeTemplate("header") ?>
<style>
    .table{
        width: 100%;
        margin-left:auto;
        margin-right: auto;
    }
    .tr,.td{
        width: 100%;text-align: center;
        vertical-align: middle;
    }
    .cust-container{
        display: flex;
        justify-content: center;
        margin-left: auto;
        margin-right: auto;
    }
      
</style>
<!-- Start of Main Content -->
<tr style="">
    <td bgcolor="#FFFFFF" align="center" style="">
        <table width="100%" align="center" cellpadding="0" cellspacing="0" border="0" class="devicewidth" style="">
            <tbody style="">
            <!-- Start Spacer -->
            <tr>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="h26" height="36" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- End Spacer -->
            <tr>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="mktEditable content mktEditable content" id="edit_text_1" valign="middle" style="font-family:Calibri, Helvetica, sans-serif; font-size:16px; color:#505050; text-align:left; line-height:25.6px; font-weight:normal; text-transform:none;">
                    <p>
                        <br>
                            <div class="cust-container">
                                <?php $residuo = sprintf("%02d:%02d", floor($line->getRemainingTime()/3600), floor(($line->getRemainingTime()/60) %60))?>
                                The Contract Line &nbsp;<b><?php echo $line->getLineNumber() . ' - ' . $line->getName()?> </b> &nbsp;<?php echo " is going low ({$residuo} Hours remaning ) ";?>
                             </div>
                        <br>
                        <br>
                       
                        <table class="table">
                            <tr class="tr">
                                <td>
                                    <strong><?php echo Deep::helper('deep_email')->__('Total Time')?></strong>:
                                    <br><?php echo sprintf("%02d:%02d", floor($line->getTotalTime()/3600), floor(($line->getTotalTime()/60) %60))?><br><br>
                                </td>
                                <td>
                                      <strong><?php echo Deep::helper('deep_email')->__('Remaining Time')?></strong>:
                                      <br><?php echo sprintf("%02d:%02d", floor($line->getRemainingTime()/3600), floor(($line->getRemainingTime()/60) %60))?><br><br>
                                </td>
                            </tr>
                            <tr class="tr">
                                <td>
                                      <strong><?php echo Deep::helper('deep_email')->__('Name')?></strong>:
                                      <br><?php echo $contract->getName()?><br><br>
                                </td>
                                <td>
                                      
                                     <strong><?php echo Deep::helper('deep_email')->__('Customer Company')?></strong>:
                                     <br><?php echo $company && $company->getId() ? $company->getName() : ''?><br><br>
                                </td>
                            </tr>
                        </table>
                        
                        
                      
                        
                      
                      
                    </p>
                </td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- Start Spacer -->
            <tr>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td height="30" style="font-size:1px; line-height:1px;">&nbsp;</td>
                <td class="w22" width="41" style="font-size:1px; line-height:1px;">&nbsp;</td>
            </tr>
            <!-- End Spacer -->
            </tbody>
        </table>
    </td>
</tr>
<!-- End of Main Content -->
<?php $this->includeTemplate("footer") ?>
				
			

And click on the “Save” or”Apply” button.

EMAIL EVENT CREATION

To create a custom mail event, you will need to go to the System -> Tools -> Email -> Event menu. At this point, you will need to click on the”Add  Event” button. At this point, it will be necessary to give a name to the event by filling in the “Name” field. We define Whether to send attachments by changing the value of the field”Send  Attachments” to “No”. Now in the “Email Template” field, we select the template created in the previous point of this guide. In the “Event Trigger” section, select “DeepService – Operation”in the “Model” field In the “Event Expression”entry. We insert the following code:

				
					if ($this->getModel()->getData('escalation_rule')){
        return true;
}
return false;
				
			

In the “To” section We insert the following code:

				
					$adminUserToNotify = 'admin';
$admin = Deep::getModel('deep_admin/user')->loadByUsername($adminUserToNotify);
if($admin && $admin->getId()){
    $adminEmail = $admin->getEmail();
    if($adminEmail){
        $this->changeLanguage($admin->getLocale());
        $this->addTo($adminEmail);
    }
}
				
			

At this point, we can go to click the “Save” or”Apply” button Now the event will have been saved

ASSIGNING THE MAIL EVENT TO THE ESCALATION RULE

To assign the mail event to the escalation rule you will need to go to the menu: System -> Service Configuration. Here you will need to go to the previously created rule or any escalation rule you want to change. In the Escalation Rule screen, you will need to select the Created event from the drop-down menu that will appear by clicking the “Email Event” field. At this point, We are going to configure the “Level” field to 0 and the “Next Level” field to 1. Since we do not want to receive the notification every time the rule runs, but only the first time. Finally we are going to configure the field “Cron  Expression”at 5 minutes using the drop-down menu located below the field itself. In the “Escalate all Records with following values (Main Filter)” field.At this point, you will need to click the “Save” or “Apply” button.

Create an escalation rule that is based on a metric

In Deepser, you can configure an escalation rule based on a metric.

This allows you to perform actions in Deepser for example when a ticket is not assigned after a certain time from its creation.

Configuring the rule

For this example, suppose we have a “Time to Respond” metric already configured, it will have as a start condition that the ticket status is “New”, and as a Stop condition that the state is any other state that is not “New”.

To configure a new escalation rule, you will need to go to the System -> Service Configuration -> Escalation Rule menu.

Here you will need to click on the “Add Rule” button.

Now the following screen will open:

At this  point  we configure the “Name” field as “Set  priority high for non-assigned ticket after 1 hour”.

We set the field “Model Alias” to “DeepService – Operation”.

Now we configure the Level to zero and Next Level field to one, that is, this rule will process all the tickets in zero state and also update the Level to avoid double processing entity.

At this moment, we set the field “Cron Expression” Every 5 minutes using the drop-down menu located below the field itself.

As the last step of this first phase, click on “Save” or “Apply” to save the rule.

CONFIGURING QUERY BUILDERS

Now configure in the newly created rule the query builder “Escalate all Records with following Timer values (applied after the Main Filter)” like this:

At this point, we have to configure the query builder “Set Records values to” like this:

Finally, we can click on “Save” or “Apply”.

Configure an escalation rule that generates other entities

Suppose you want to configure an escalation rule that gives high priority to all tickets whose requesting company is “Acme International” and that adds a comment not visible to users that reports some quick contact information for the operator who will have to handle the request.

To do this you will need to go to the System -> Service Configuration -> Escalation Rule menu.

Here, you will need to click on the “Add Rule” button.

Now the following screen will open:

At this point, we configure the “Name” field as “High Priority Acme International” and load Primary Contact Information”.

We set the “Model Alias” field to “DeepService – Operation”.

Now configure the Field “Level” to 0 and Next Level to 1, that is, this rule will process all the tickets whose level is zero and then change this level to 1 so as not to reprocess the same tickets.

Please pay attention that in the case of several escalation rules active at the same time and potentially changing the level.

At this point, we set the field “Cron Expression” Every 5 minutes using the drop-down menu located below the field itself.

As the last step of this first phase, click on “Save” or “Apply” to save the rule.

CONFIGURING QUERY BUILDERS

Now configure in the newly created rule the query builder “Escalate all Records with following values (Main Filter)” like this:

Now configure in the rule just created the query builder “Set Records values to” like this:

At this point in the “Output section (Script)” we are going to insert the following code:

				
					$entityId = $this->getModelOutput()->getId();
$company = $this->getModelOutput()->loadRequesterCompany();
if($company && $company->getId()){
    $primaryContactUserName = $company->getData('primary_contact');
    $primaryContact = Deep::getModel('deep_admin/user')->loadByUsername($primaryContactUserName);
    if($primaryContact && $primaryContact->getId()){
        $primaryContactName = $primaryContact->getFirstname() . " " . $primaryContact->getLastname();
        $primaryContactEmail = $primaryContact->getEmail() ? $primaryContact->getEmail() : "" ;
        $primaryContactPhone = $primaryContact->getPhone() ? $primaryContact->getPhone() : "";
         
        $Description = nl2br("\n=================================================================\n
                                 Nome Referente: {$primaryContactName}\n
                                 Telefono Referente: {$primaryContactPhone}\n
                                 Email Referente: {$primaryContactEmail}\n
                                =================================================================\n");
         
         
        $comment =  Deep::getModel('deep_activity/activity');
        $comment->setPortalVisibility(0)
                ->setType(1)
                ->setModelId($entityId)
                ->setModelAlias("deep_service/operation")
                ->setDescription($Description)
                ->setStatus(1)
                ->save();
         
    }
}
				
			

Now we can click on “Save” or “Apply”.

Groups

Once the Users are created, Deepser allows you to organize them into Groups.

Groups are intended as work groups of backend user (Key-User, Agent, Admin) or End-User. A user can be part of several groups.

In Deepser, through groups, you can manage two fundamental aspects: record assignment and visibility.

RECORD ASSIGNMENT

Once the group configuration is complete, records can also be assigned to groups.

For example, in the Service module, we can define the assignee group of a request.

Once the group has been selected, even the select-box with the users assigned to the record is automatically filtered according to the members of that group.

RECORDS VISIBILITY/MODIFICATION/DELETION PERMISSIONS

 Deepser allows you to filter, according to the groups to which the user belongs, the resources he can access.

It also allows you to define which permissions (visibility, modification, deletion) on records have the different teams of users within the modules they can access.

Importing Data

This class is specific to importing data in Deepser. You will learn how to use Deepser’ Import Tool to create models in Deepser from Every well formatted File.

Deepser allows you to easily import entities from an external data source.

A way to do that is to configure an Import procedure from the web interface of the software.

Another way is using the API. There is a library, in a public GitHub repository also to use Deepser integration. The library is at: https://github.com/deepser/api-php

We offer also the possibility to ask for Professional Services of Deepser and have a certified Project Manager / Consultant of Deepser to implement the integration for you.

Think about those large Excel files filled with thousand of rows of data, you can automatically import their content in Deepser to manage and organize them through a user-friendly web tool, you can even schedule imports to always keep you data up to date.

Articles

  • Import Foundamentals
  • Import Creation
  • Import Basic Data Binding
  • Import Before Run
  • Import Before Run Tutorial
  • Import Before Row
  • Import Before Row Tutorial
  • Import After Row
  • Import Binding The Unique Field “Code”
  • Import Binding the Type Value
  • Import Binding the Dates Values
  • Import Binding a Company, creating the record if it doesn’t exist
  • Global Import

Import Foundamentals

To configure a new import procedure, please go to the menu: System > Tools > Import.

In the first page after clicking on the menu, you can see a grid of all Imports already configured in your Deepser.

To see the configuration for a specific import, click on the row in the grid. Press ‘Add Import’ to create a new one.

Then we can see the Import configuration form:

The Fields have the following meaning:

FIELDMEANING
NameName of the Import.
ModelModel of the entities that are going to be imported into Deepser (Operations, CI, Companies etc.).
TypeFormat of the source file containing the records to be imported in Deepser.
Has Header (Yes/No)The first row of the file is an header. If Yes, Deepser will ignore the data of the first row of the Excel File.
Cron ExpressionIf the first row of the Excel file is a document header, it cells can be automatically recognaised as entity fields, this comes handy during the binding process
StatusIf Enabled the import will run, otherwise not.
File PathIt is used to upload the source file containing the records to be imported.
Path ExpressionIt is used to dynamically change the name of the file, containing the data to be imported. We will explain this field with an example, below in this document.
Entity – File – CodeIn this field there is the configuration of the ‘File Column – Entity Field’ binding. Entity: Model field; File: File column; Code: script to perform specific manipulations of data on the column value (e.g.: format a date, convert a value, etc.), executed during the cell evaluation.
Before RunCustom PHP code to be executed before the import procedure starts. It is used (see examples below) to pre-load data in memory, in order to avoid subsequent massive SQL queries to the DB. e.g.: Load the content of a DB table inside an Array. This action can then be used during the import, to avoid querying the database for every Excel file row.
Before RowCustom PHP code to be executed before each Excel file row is imported. It is used (see examples below) to dynamically change the values of the row imported. e.g.1: for every row imported we want to set the status as “New”. We can specify that inside this field. e.g.2: we want to load a record of the DataBase instead of importing a new record. We can load the record from the DataBase here, or read the record from the Before Run Array, representing the data on the DB Table.
After RowCustom PHP code executed after each row, as soon as every single record has been saved. It is executed multiple times after every row insert/update.
After RunCustom PHP code executed after all Excel file rows have been imported. It can be useful to perform custom tasks at the end of the import.

Import Creation

1 – At first, start by choosing a name for the import procedure and the model of the entity to be created

2 – Then select the appropriate file extension, and if it contains an header, set “Header” to yes.

2b – if the file is a .CSV, configure the appropriate delimiters and enclosures (character used to end a line)

The field “Type” defines the file format.

It can be “CSV” or “XLS”.

These are the standard formats supported by Deepser.

As you can see in the example file attached below, each row will be treated as a single record to import, each column as single Model Field:

CODENAMETYPESUBTYPESTATUSACTIVATION DATES/NNOTESOWNER COMPANYASSIGNED USER
106545Apple Iphone XIMobilesSmartphonesActive15/03/2019LFC6370742Scratches on the screenINTODEEP srl4\euler
106546Datapower 45ServersPhysical ServerActive20/12/2019LEV6267443 INTODEEP srl4\riemann
106547Dell EM5000ComputersWorkstationsActive5/04/2020LF96128119 INTODEEP srl4\riemann
106548HP Pavilion 15SComputersLaptopsActive23/04/2020L8M6200959Noise coming from cooling fanINTODEEP srl4\riemann

Table1: example of an Excel File to import devices as CMDB Cis

3 – Remember to change the status to “enabled”, then click on the Upload button under  “path label”.

4 – After the upload occurred, Deepser will recognise every field name in the document header, if present, the next step is the binding process.

Import Basic Data Binding

FIELD CONFIG: ENTITY – FILE – CODE

This field is used to perform the binding (also called “mapping”) between each column of the source import file (Excel file) and the fields of the selected model in the Database, so that deepster can populate every field of its database with the correct corrisponding value.

Entity: this column has a list of fields from the entity inside the Database of Deepser. It is the list of fields (also custom fields) present in the DB table for the Model Selected. E.g.: if you select “DeepCmdb – Ci” Model, here you will find all the fields of the CIs in the Deepser database table deep_cmdb_ci.

File: it represents the column of the Excel import file, which is read. It is selected from a select-box containg the names of columns in the File header (first row of the Excel).

Code: by clicking the button in the code column, a scripting area will open. The PHP code in this area will be executed when the value of the single column selected is evaluated and saved.

1 –  To define a new binding occurence, simply click the “+” button (light blue, below the fields list), to delete it, instead click on the red ‘minus’ button on the right side.

2 –Now you can bind each field(column name) from the source file to the corrisponding one in the Deepser entity model.

3 – Once the binding is completed, everything is set up for a basic import procedure, and you can start the process by saving and then clicking on the yellow ‘Run’button, or schedule the import to recur over time. If everything went well, a green label should state how many entities were affected.

Import Before Run

OVERVIEW

Sometimes there’s the need to import files with complex data types, or to avoid creating duplicates, etc., for all these needs the code section is essential, there are 4 main coding section, plus one for each entity field.

BEFORE RUN

The scripting area “Before Run” is were to put Custom PHP code that has to be executed before import procedure starts.

It is commonly used to retrieve records from the DataBase and to put those records inside an Array, in order to avoid multiple select queries on the DB.

Typically, data retrieved are the same model of the import. But we can use this scripting area also to pre-load related models. For example, if we are importing CMDB CI records, we could pre-load a collection of CMDB Types and CMDB Subtypes inside this scripting areas.

The collections are typically stored inside variables, that are available also inside the other scripting areas.

Attention: if you use the same name of a PHP variable, it will be overwritten.

Import Before Run Tutorial

In the following example we are retrieving devices already inside Deepser’s DataBase, to avoid duplicates when importing new records from an Excel.

We’re also retrieving Companies, Types, Subtypes and Status List Values to convert their names to corresponding IDs.

				
					/* through the static method in Deep class, a collection of CI is retrived. The collection is filtered by class_id = 2 that represents the 'Device' class*/
$deviceCollection = Deep::getResourceModel('deep_cmdb/ci_collection')->addFieldToFilter('class_id',['eq' => 2]);
/*  declaring array containing device instances */
$deviceArray = [];
/*  each element of the collection is saved in an associative array, having as key the CODE field (first column of the import file) and as value the instance of the Device. The instance is a PHP object with all the data inside the Database for the record */
foreach($deviceCollection as $device){
    $deviceArray[$device->getCustCode()] = $device;
}
 
/*  declaring an array containing type-subtype tree */
$subtypesTree = [];
/*  declaring array used for id->name type traslation */
$typeIdentity = [];
/*  retrieving CMDB Type collection through static method getResourceModel in Deep class */
$typeCollection = Deep::getResourceModel('deep_cmdb/type_collection');
/*  retrieving CMDB Subtype collection through static method getResourceModel in Deep class */
$subtypeCollection = Deep::getResourceModel('deep_cmdb/subtype_collection');
 
foreach ($typeCollection as $type){
    /*  for each type, the array tree is populated assigning the name of the type converted into uppercase    
        and a child array as a value, whose key 'id' corresponds to the type id
    es: arrayTree [typeName] ['id'] = typeId */
    $subtypesTree [strtoupper($type->getName())] = ['id' => $type->getId()];
    /*  for each type, the identity array is configured by assigning the id as key and name
    converted uppercase as value the name attribute transformed into uppercase */
    $typeIdentity[$type->getId()] = strtoupper($type->getName());
}
 
/*  for each subtype, the types in the array tree are updated by updating child array, adding the element
    that represents a subtype having as key the name of the subtype transformed into uppercase, and as 
          value the id of the subtype. eg: arrayTree [typeName] [subtypeName] = subtypeId */
foreach ($subtypeCollection as $subtype){
    $subtypesTree[$typeIdentity[$subtype->getTypeId()]] = array_merge($subtypesTree[$typeIdentity[$subtype->getTypeId()]], [strtoupper($subtype->getName()) => $subtype->getId()]);
}
/*  retrieving Company collection through static method getResourceModel in Deep class */
$companyCollection = Deep::getResourceModel('deep_company/company_collection');
$companyArray = [];
foreach($companyCollection  as $company){
    /*  for each company, the array is configured by assigning as key the company name
transformed into uppercase and company id as value */
    $companyArray [strtoupper($company->getName())] = $company->getId();
}
 
/*  Retrieving values and keys of cmdb_ci_status list
Deep::helper('deep_list')   retieving list helper which is an utility class
->loadListValues('cmdb_ci_status')  retieving list elements
->toOptionHash()    the return collection is converted in a key = label array
array_flip      wrapping keys with vakues
array_change_key_case       keys case converted to uppercase */
$statusArray = array_change_key_case(array_flip(Deep::helper('deep_list')
        ->loadListValues('cmdb_ci_status')->toOptionHash()),CASE_UPPE
				
			

Import Before Row

The PHP code in the “Before Row” scripting area will be executed before each row of the import file is evaluated field by field.

It is very important to highlight the meaning of the $model variable.

The $model reserved variable is used to populate data of the entity that will be imported.

It is a PHP Object of the same type of the Model field specified in the Import. So, for example, if the Import is related to a DeepCmdb – Ci Model, then the $model variable will contain a Deep_Cmdb_Model_Ci Object. It represents a record of the Cmdb Ci Table in the Database.

It is also very important to highlight the meaning of the $data variable.

The $data reserved variable is used to expose data of the current Excel file row.

It is a PHP Array containing the values of every column of the Excel current row.

So, in the Excel reported above (see Table1), the variable $data will contain the following value for the first row of the Excel:

$data[0] = “106545”
$data[1] = “Apple Iphone XI”
$data[2] = “Mobiles”
$data[3] = “Smartphones”
$data[4] = “Active”
$data[5] = “15/03/2019”
$data[6] = “LFC6370742”
$data[7] = “Scratches on the screen”
$data[8] = “INTODEEP srl”
$data[9] = “4\euler”

Starting from the variables described before, the Before Row is used to retrieve a model from the database starting from an alphanumeric value.

So, for example, if a record must be loaded by CODE column in the Excel (see Table1) and not for ID, in the before row you can load the record with that code, starting from the Excel and the Database of Deepser.

In this case, the original DB record, once loaded into the $model variable, can be updated with the values in the current Excel file row, instead of creating a new record for every Excel row.

Import Before Row Tutorial

In the following example the column “CODE” is checked. If it is not empty and another Device with the same code already exists, the device will be updated with data in the current row of the import file.

Without this check, a new device would be created.

				
					/*  the Excel file column with index 0 (column A) containing the CODE field is evaluated.
the $data array represents the current line of the import file and it has all
its values accessible via the Excel column index. The index starts from 0. */
$deviceCode = trim((string)$data[0]);
/*  if the column containing the attribute 'CODE' is not empty */
if($deviceCode){
    /*      if a device with same CODE already exists
    the $deviceArray array was created with key = CODE and value = instance of the device
    in 'Before Run' area */
    if(array_key_exists($deviceCode,$deviceArray)){
        /*  the instace of the device already present, with the same code, is assigned to
    the $model object
    $model object represents the current instance of the
    Deep_Cmdb CI model (specified in the Model field of the import configuration)*/
        $model = $deviceArray[$deviceCode];
    }
    /*  the class_id attribute is set by default to 2 (Device) */
    $model->setClassId(2);
}
else {
    /*  if 'CODE' is empty, the current model is set to null to avoid saving
    any empty or incomplete records */
    $model = null;
}
				
			

Import After Row

The PHP code in the “After Row” area is executed after the record in the current Excel file row has been saved into the Database.

Usually, in this area, you can set all the fields that don’t have a corresponding column in the import file, because they are calculated starting from other fields’ value.

Another use case is when you need to update the array of objects created in the “Before Run” area used to verify the uniqueness of a record. After an insert, you should add the new record to the original data collection / array created when the import starts.

Import Binding The Unique Field “Code”

The following examples refers to the code present next to each entity field

Here you can use the $value variable to get the current column’s value.

The following example shows the PHP code for binding the “CODE” field with no spaces at the beginning or at the end of the string.

This is a very important safety check for key fields and we suggest to perform this check every time you want to import a key field or a calculated key field.

				
					/*  $value contains the value of the current column in the import file, calling trim()
method (after casting as string type) to eliminate any space at the beginning or
at the end of the string */
$value = trim((string)$value);
/* after spaces were removed, the 'CODE' present in the import file is saved in the
cust_code field of the current model */
$model->setCustCode($value);
				
			

Import Binding the Type Value

The following example shows the code used to bind the “TYPE” field, assigning to the $model, the id of the Type which is specified using a name in the import file.

This example is very useful if we want to import data not with their keys, but with their alphanumeric (human readable) values.

				
					/*  $value contains the value of the current column in the import file, calling trim()
method (after casting as string type) to eliminate any space char at the beginning or
at the end of the string */
$value = trim($value);
/*  if $value isn’t null and isn’t empty */
if($value){
    /*  if the type name exists in DeepDesk. This is checked by testing if the name in the Excel file is a
    key in $subtypesTree array, created in the 'Before Run' scripting area */
    if (array_key_exists(strtoupper($value), $subtypesTree)) {
        /*  the type id is retrieved from the subtypesTree array and saved in the field
    type_id of the current model */
        $model->setTypeId($subtypesTree[strtoupper($value)]['id']);
    }
    else {
        /*  if the type name specified in the file doesn't exist in DeepDesk, then type_id
    is set to null */
        $model->setTypeId(null);
    }
}
else {
    /*  if no type name has been specified in the import file, then type_id
    is set to null */
    $model->setTypeId(null);
}
				
			

Import Binding the Dates Values

In the example below, the ACTIVATION DATE column is converted to Database format and assigned to the Activation Date model field.

				
					/*  the conversion is surrounded with a try-catch to avoid throwing exceptions */
try{
    /*  a DateTime object is created from the format used in the import file */
    $date = DateTime::createFromFormat('d/m/Y', $value);
    /*  the field 'cust_activation_date' is set with the created date formatted in the Database
    accepted format */
    $model->setCustActivationDate($date->format('Y-m-d'));
}
catch(Exception $exxx){
    /*  any exception is printed to the import_device.log log file, if the file doesn't exist
    it will be created */
    Deep::log($exxx,null,'import_device.log');
    Deep::log('value: '.$value, null, 'import_device.log');
    Deep::log('date: '.$date, null, 'import_device.log');
}
				
			

Import Binding a Company, creating the record if it doesn’t exist

The following example shows how to set the Owner Company model field with the ID of a company which has been specified by name in the import file. If the company doesn’t exist then it is created.

This example is very import, because it demonstrates how to create a related entity starting from a value specified in the Excel File.

				
					/*  $value contains the value of the current column in the import file, calling trim()
method (after casting as string type) to eliminate any space at the beginning or
at the end of the string */
$value = trim((string)$value);
/*  if the company name field specified in the import file is not empty */
if($value) {
    /*  if the company name (transformed into uppercase) doesn’t exist in DeepDesk.
    Here we are checking the keys of $companyArray created in the 'Before Run' area */
    if(!array_key_exists(strtoupper($value), $companyArray)){
        /*  a new Company object is created through the static getModel() method of the Deep class (
    via the abstract factory pattern)*/
        $companyModel = Deep::getModel('deep_company/company');
        $companyModel->setName($value);
        $companyModel->setStatus(1);
        /*  saving the company to Database after setting the name and the status (1 = Enabled) */
        $companyModel->save();
        /*  adding the company just created to the $companyArray */
        $companyArray[strtoupper($value)] = $companyModel->getId();
    }
    /*  the field owner_company_id of the CI is set here.
        The id is calculated starting from the name of the company specified in the import file */
    $model->setOwnerCompanyId($companyArray[strtoupper($value)]);
}
				
			

Global Import

In Deepser, the configuration and execution of system imports is the exclusive prerogative of administrative users.

In any case, it is possible to give the possibility of executing imports already configured and tested by administrator users to other types of backend users as well.

This possibility is provided by global imports.

Global Import configuration

The configuration of an import as a “Global import” must always be carried out by an administrator user following the configuration and testing phase of the configured import.

In fact, within an import record we find the following fields:

These fields are not visible by default on the Import Form, so to make them appear, you need to edit the Formtemplate and add them.

Field

Definition

Enable Global Import

It’s a toggle button which indicates if we want this import procedure to be visible to other users expect admin or not. By toggling “Yes” the current import procedure will be shown on the global imports grid.

Global Import Groups

It’s a multiselect field in which you can choose the user groups that will have visibility to this global import procedure.


As the first step in configuring global import settings, it is necessary to ensure that the role of the user(s) who need visibility of the import has the ‘Global Menu’ enabled and specifically the ‘Import’ action available as a resource in their role.:

Global import using

Once all the configuration has been completed, users will be able to access the global imports section directly from the global menu at the top right of the screen (icon “…”):

By clicking on the relevant section, you can access the screen with the list of all the global imports accessible:

By clicking on the desired import, it will be possible to access the details, where it is normally possible to upload a file used for the import.

Once the file has been uploaded, it will be possible to perform the import by clicking on the respective “Run” button on the right top corner:

Groups Creation

To create new groups in Deepser, or manage existing ones, go to the menu item System-Permission-Groups. This menu is accessible only by Administrator role user.

At this point the main grid of the groups will be shown.

To add a new group click on the button (top right, circled in the picture) ‘+ Add Group‘.

 

At this point the group creation form will open.

The fields of the form have the following meaning

FieldMeaning
NameThe name of the group, displayed inside the select-boxes and grids in the system.
StatusIndicates whether or not the group is active in the system.
EmailThe group email (if any), to send automatic notifications to the email box dedicated to the team.
LevelThe level of support of the group. It is a useful number for Service Desk measurements and automation. For example, if you want to measure the working time of all top-level support teams, set level 1 to all top-level support groups in your organization.
Company VisibilityA user who belongs to a group with this field enhanced sees only the data of his company or sub-companies. In the case of a user with User type, this field is by-passed, because the user sees only the data of his Company.   Note: the same field is also present in the individual user form, so the system will first try to apply the setting at the user level; if it is not set, apply the setting at the group level.
DescriptionThe description of the group. Data used to keep internal notes on the configuration or meaning of the group.

IT Asset Management

This Course will explain everythin about ITAM Configuration and Usage, from Deepser’s own remote collector, to the various job rules and monitoring you can do to each device.

The IT Asset Management module allows you to keep an automated archive of the Assets whose information is updated and sorted automatically, it is also possible to consult and modify the data of each resource manually via the web interface.

Articles

  • IT Asset Models
  • ITAM Automatic Scan Configuration and Usage
  • ITAM Configuration
  • AnyDesk
  • Supremo

IT Asset Models

To access the available models for the IT Asset module, go to the main menu and navigate to the “IT Asset” section:

From here, we can find various usable models. In the following articles there is a detailed description of each

ITAM Device

To consult all the devices added to “IT Asset Management” module, go to the Asset>Device section in Deepser back-end.

From there you can see the Devices and organize them into by configuring your custom grids and access the form containing their data to modify them if it is necessary.

From this section, you can manually add a device using the ‘Add Device’ button. Anyway, for this purpose, you can use the CMDB module. The difference is that the IT Asset module is designed to automatically retrieve devices, unlike the CMDB module through which management of devices is only manual.

To add a new Device by agent, you can click on the ‘Download Agent’ button (Agent installation procedure is illustrated here). Once the agent is downloaded and configured your current Device will be added as a record on the grid.

Licenses in use: Available at the top of the page, it indicates the available number of devices that can be added. In fact, the devices in this module are subject to licensing.

Device Tab & Fields

By clicking on a Device in the grid, you can access the form containing its data, such as:

  • CPU
  • BIOS
  • HDD
  • Network Interfaces
  • Operating System
  • RAM
  • installed software

In device edit or creation, the following tab and fields are available:

Device Data Tab

On Device Data Tab, there are the main information of a device. Below is the detail:

Field

Description

Name

Text field with the retrieved Device’s name.

Device Name

The retrieved Device’s name

Status

Select field with two values: enabled or disabled. Initially its value is set to enabled.

Type

Select field where you can choose a device type. It has already some pre-configured values such as: physical, virtual, other and unknown.

Subtype

Select field where you can choose a device subtype. Each subtype value is linked to a type.

Description

Text area field where can add a description for your device.

Serial Number, Model Name, Vendor Name, Domain, Last Username, Last User Domain

Text fields which are auto populated from agent, with the current device’s corresponding data.

Last Scan At

Datetime field which indicates the last time this device was scanned by an agent or remote collector.

Last Seen At

Datetime field which reflects the last time the device was observed to be active and responsive.

In Service

Select field with two values: ‘Yes’ and ‘No’, which indicates if the device still has the agent downloaded and is currently active and operational within the network.

Hardware Tab

On Hardware Tab, all device’s hardware such as BIOS, System Chassis, CPU, RAM, Network Interface etc.

All device-related hardware information is stored in different grid fields. Each grid record has an action column, which you can click to view further details on the related hardware data. 

Software Tab

Under “Software” tab, there are all software information related to the main device. We can find the following grids:

  • Operating System: Grid field which stores all the information related to the device’s operating system.
  • Software: field which stores all data about software programs installed in your device.

Users Tab

In the Users Tab you can relate client information to the device.

 

Field

Description

Owner Company, Assigned Company

Select fields with values retrieved from Company model.

Owner Group, Assigned Group

Select fields with values retrieved from Group model.

Owner User, Assigned User

Select fields with values retrieved from User model.

Monitoring Tab

Through “Monitoring” Tab, you can monitor your device’s data:

The available fields are:

Field

Description

Remote Control

Select field which allows you to connect and take control of the device remotely.

Monitoring Data

It shows a graphical representation of your device resources usage during a period of time.

Metrics

Multiselect field where you can choose the resource usage that you want to show on the graph.

Period

Select field where you can choose timeframe for displaying data.

ITAM Software

To consult software added to ‘IT Asset Management’ module, go to the Asset>Software>Software in Use section in the Deepser back-end.
On this model are saved all the software programs data, retrieved from the devices.

The software installed on collected devices is automatically added to Deepser.

You can also organize software by configuring custom grids and manually add new records.

By clicking on a Software entry in the grid, you can access the form containing its data:

 

The available fields for this module are:

Field

Description

Name

Text field with the retrieved software’s name

Vendor

Text field with the related vendor of the software

Version

Text field that indicates the current version of the software

Install Date

Datetime field which indicates the date the software was installed.

First Scanned At

Datetime field which indicates the date when the software was scanned on the device.

Identifying Number

Text field with a unique string to identify the software.

Device

Text field where it is saved the device Id connected to this  software

Description

Text area field where you can add a description for the software

ITAM Network

The Network model is designed to manage and organize network information, typically for assets or devices within Deepser. This model includes two types:
  • Subnet: This type stores information about network subnets. It helps in organizing and managing large ranges of IP addresses by grouping them into subnets. You can configure various attributes related to the subnet, such as its range and any relevant network settings.
  • IP Address: This type stores specific details about individual IP addresses within the defined subnets. It allows for the tracking and management of each IP address, including its assignment status, associated device, and any additional configuration details.

Together, these types provide a comprehensive framework for managing network infrastructure, ensuring that both broad subnet information and detailed IP address data are effectively organized and accessible.

Subnet

We can access existing Subnet or manually create one from the main menu: “IT Asset > Network > Subnet”.

By clicking on “Add IP Address” or selecting an existing record, the following screen will appear:

For Subnet editing or creation, the following fields are available:

Field 

Description 

Name 

Text field which is used to indicate the name of subnet. 

Network Address 

Text field which indicates the base address of the subnet. This field is populated by a CIDR IP address.

Bitmask 

The subnet mask in bit form, indicating the number of bits used for the network portion of the address. 

Range Start 

The first usable IP address in the subnet. 

Range End 

The last usable IP address in the subnet. 

Gateway IP Address 

The IP address of the gateway or router for the subnet, used for routing traffic outside the subnet. 

Gateway Mac Address 

The MAC address of the gateway or router associated with the Gateway IP Address. 

Subnet Unique Id 

A unique identifier for the subnet within the system 

Last Seen At 

Datetime field indicating the last time this subnet was observed or updated. 

Status 

Select field in which you can enable or disable the subnet. 

Subnet IPs 

Grid field where there are shown all the ips connected to this subnet. 

IP Address

We can access existing IP addresses or manually create one from the main menu: “IT Asset > Network > IP Address”.

By clicking on “Add IP Address” or selecting an existing record, the following screen will appear:

 
For IP address editing or creation, the following fields are available:

Field 

Description 

IPv4 Address 

Text field where IPv4 address is stored. 

IPv6 Address 

Text field that stores an IPv6 address. Allowed format for this field is the standard notation of IPv6

Subnet 

Select field with all the available subnets which can be connected to this ip. 

Device 

Select field which links the device with this ip address. 

Network Interface 

This field is used to select the network interface associated with the IP address. It could refer to a physical or virtual interface on a device. 

Status 

Select field which can ‘enable’ or ‘disable’ this ip address. 

ITAM Management

The Management model in Deepser is designed to streamline device administration by executing preconfigured scripts, tracking, and managing device updates. This model includes three distinct types: Scripting, Updates, and Jobs.
  • Scripting allows administrators to automate tasks by running predefined scripts on devices, reducing manual effort and ensuring consistency.
  • Updates enable the monitoring and deployment of software updates across all devices, ensuring they remain secure and up-to-date.
  • Jobs provide a way to schedule and manage recurring tasks or operations, offering flexibility and control over routine maintenance.

Below are the detailed operations of each type.

Scripting

We can access the “Scripting” type from the main menu: “IT Asset > Management > Scripting”

Within the Scripting type, there are two separate sections:

  • Script: In this section, you can view and manage predefined scripts that are available for execution on devices. You can also create new scripts by clicking the “Add Script” button. These scripts can automate various tasks and operations on your devices.
  • Run History: This section provides a detailed log of all script executions. It shows the history of scripts that have been run, including information such as the date and time of execution, the status of the script, and any errors or issues encountered. By clicking on individual log records, you can access detailed information about each execution, including which devices were affected and the results of the script.

These sections allow you to effectively manage and monitor script usage, automate tasks, and review the outcomes of script executions.

Script

Clicking on “Script” we can access to the list of predefined script that can be execute on your device (and cannot be modified):

However, you can also create your own script to execute by clicking on the “Add Script” button located at the top right corner of the screen: 

The fields available in the script model are the following:

Field 

Description 

Name 

The name for your script

Type 

With this field you can choose the type of your script:

•          Batch

•          Powershell

•          Bash (Linux/Mac)

Scope 

With this field you can choose if the script should be run for all system users or for the current user.

Category 1

Categories are used to categorize the script you are creating.

Category 2 

Description 

A field to describe the script you are creating.

Content

This field should contain the command you want to execute. In this field should be inserted powershell, batch or bash commands.

Execution Timeout

Waiting time before the script is marked as not completed successfully.

Arguments

With this field you can provide additional parameters to the script.

User Defined 

This field is read-only and indicates whether the script was manually created by a user.

Existing scripts have this field set to “No”.

Status

With this field you can enable or disable the script.

Script Example

Below an example of an existing script:

This script allow a user to clean up a disk with a PoweShell command. It can be identified by “Type” field (Powershell) and the “Content” which contains the commands to be sent to a device.

Execute Script

To execute a script on a device, you need to access the specific device, and at the top right corner of the screen, you can use the green “Run Script” button:

Clicking on the button will open a new screen: 

From here, you can choose to execute either a user-defined script (on the left side) or a script from the System Library (on the right side).

Clicking the “Run” button next to a script will execute it.

Additionally, the “Run History” button at the top center of the screen allows you to access the history of executed scripts (“Run History” section).

Run History

As previously mentioned, the Run History section enables users to check and verify results of executed scripts:

By clicking on a history record we can see the following information: 

Below is the detail of their operation:

Field 

Description 

Script 

History related script. 

Device 

Device on which the script was executed

Execution Status 

This field determine the execution status. 

Sent By 

The user who sent the command. 

Sent At

The date when the command was sent to the server.

Executed At

The execution date. 

Output 

The output received from the sent command.

Return Code 

Exit status or result code returned by sent command. 

Updates

We can access “Updates” type from the main menu: “IT Asset > Management > Updates”.

In this section, you can find a list of all available updates detected by the remote collector on the scanned devices. This includes:

  • Updates Available for Installation: These are updates that have been detected on the scanned devices but have not yet been installed. The list shows which devices can receive these updates.
  • Updates Already Installed: These are updates that have already been applied to the scanned devices. The list indicates which devices have successfully installed these updates.
  • Update Details: For each update, you can view additional information such as the update name, version, release date, and any relevant descriptions or notes.
  • Installation Status: See the number of devices where each update is pending installation or has been installed. This helps in monitoring the update deployment process.
  • Filter and Search Options: You may have options to filter or search for specific updates, platform and other data making it easier to manage and track updates across your IT infrastructure.

This comprehensive view helps you effectively manage and oversee the update status of your devices, ensuring that all necessary updates are applied and monitored

 

In the “Available For Devices” column of the grid, you can see which scanned devices can receive the update. The number in the blue box indicates how many devices the update can be installed on. 

Clicking on the blue box will display a list of devices on which you can install the update: 

In the “Installed On Devices” column of the grid, you can see which scanned devices have had the update installed. The number in the gray box indicates how many devices have received the update. 

Clicking on the gray box will display a detailed list of devices on which the update has been installed. Depending on the type of update, you may also have the option to uninstall it: 

Job

We can access the “Job” type from the main menu: “IT Asset > Management > Job”. Within the “Job” type, there are two separate sections:
  • Configuration: In this section, you can create, view, and manage job configurations. This includes setting up new jobs, defining parameters, and scheduling tasks. It allows you to configure how jobs are executed, including specifying details such as target devices, job types, and execution schedules.
  • Event Log: This section provides a comprehensive log of all job executions based on your configurations. Here, you can review the history of job runs, including details on the status of each job, any errors encountered, and the outcomes of the execution. This log helps in monitoring job performance and troubleshooting issues by providing insights into job activities and results.

These sections help manage and track the execution of jobs within Deepser, ensuring effective job management and performance monitoring.

Configuration 

With a Job, a user can automate the release of updates on scanned devices. To create a new Job Configuration, click on “Add RRM Job” after accessing the Configuration section: 

The following screen will appear: 

For a job configuration, the following fields are available: 

Field  

Description  

Name  

Text field that identifies the job configuration.  

Platform  

At the moment, only Windows platform are supported.   

Cron Expression  

It allows you to define the run interval of the job. 

Install Update Types 

Multiselect field through which you can choose the types of updates you want to handle with the job configuration. 

You can select the following types: 

  • Optional 
  • Reccomended 
  • Important  

Device Exp In  

Using this query builder field, you can filter the devices to be included in the job configuration. 

Device Filter (Script)  

In the scripting area field, you can define the criteria to filter the devices that should be included in the job configuration. 

It can be used for more complex filtering based on device data. 

Status  

Select field which can ‘enable’ or disable the job configuration.  

  

Event Log 

n the “Event Log” section of Management, you can view all job configurations executed according to your settings. This section contains a log of job executions: 

Clicking on a single log record will provide information about the update (or uninstalled update) on a device, details of the installed update, and the job that was executed: 

ITAM Automatic Scan Configuration and Usage

ITAM Agents

The first step to actively use the ITAM module, and then begin the automated introduction of Devices in Deepser, is the installation of the Agent.

The Agent is a lightweight Windows application that collects all available information regarding the device on which it is installed, and then systematically sending it to the server.

Once installed, the Agent can be converted in few simple steps into Remote Collector, so you can collect data by scanning the company network, or the subnet on which it is connected.

ITAM Agent Installation

To install the Agent go to the Deepser back-end, from the menu access the Asset>Device section, click on the “Download Agent” button at the top right (as shown in figure).

The installer will be downloaded.

All the information necessary to configure communication with the Server (URL, port) is contained in the name of the executable.

Run the installer (requires Administrator privileges) and, if necessary, modify the pre-filled connection parameters; finally click on the install button to start the installation.

Once the installation is complete, on the device desktop, an icon named ‘Portal’ and a new start menu entry named ‘DeepAgent’ menu will appear.

By clicking on the ‘Portal’ icon you will be redirected to the opening page of a new Ticket where the device in use will be automatically set in it. The proposed type of Ticket created through the Agent can be changed in the Portal configuration section.

To ensure installation has taken place correctly and there are no communication problems, go to the Device section of the Asset module from the Deepser back-end menu (Asset>Device).

In this section, the record representing the device on which the Agent has been installed will be displayed.

To access the Agent user interface, click on the ‘DeepAgent’ entry added to the Start Menu.

In the first tile, the one with an icon representing an “eye”, you can check the status of the ‘DeepAgent’ service.

In the second tile, the one with an icon that represents a “wifi” network connection, there is the interface for converting an Agent into a Remote Collector (the conversion process will be discussed in the dedicated section).

ITAM Remote Collector

A remote collector is a component in a network monitoring or management system designed to gather data from various devices and systems within a network. In Deepser you can configure a device as a remote collector, if that device has agent downloaded and by clicking on the button ‘Convert to RC’, within the Asset – Device model.

The first step for collecting information in Agent-less mode is to configure a Remote Collector, a small-sized Windows application, which allows you to:

  • Retrieve data from devices on the same network
  • Acquire data from the device on which it is installed
  • Send collected data to the main appliance

It is possible to configure more than one, this is necessary for particular corporate network configurations, for example, if the network is organized in subnets isolated among them.

It is recommended to install the Remote Collector on a Windows computer that can communicate through the network with as much devices as possible, in order to reduce the number of Remote Collectors needed.

 

ITAM Agent to Remote Collector Conversion

To install a Remote Collector you need to have previously installed an Agent, which can be converted into a Remote Collector through some simple steps that can be done directly from the user interface.

Currently, Deepser offers two options to archive this conversion. Manually, using the interface, or automatically, using the ‘convert’ button.

AUTOMATIC CONVERSION

1- The first step to Automatically convert a regular Agent to a Remote Collector is to open the Agent form, through Asset > Device, then select the Agent you want to convert.

2 – Then, press the Convert to RC button, this will trigger the conversion request.

3 – A Dialog will open, asking for confirmation, click YES.

3b – The request will be sent, press Enable to get to the Remote Collector Grid.

4 – If the process finished without errors, the remote collector will be available, open it.