enter image description here

InBox ContractManagement

Version 7.0.1

Creation date 2018-03-03


Create Contracts

This module allows the creation of contracts, where a customer is associated with a contract and the calls that are opened to the customer, are associated with the contract.

Manage Contracts

We can also manage contracts by consuming hours.



The following versions of the Znuny framework are supported:

  • 7.0.x


The following modules are required:

  • InBox Core 7.0.1 or superior

Operational system

The following operating systems are required:

  • [None]

Third Party Software

The following third party software is required:

  • [None]


bin/znuny.Console.pl Admin::Package::Install /path/to/InBox\ ContractManagement - 7.0.1.opm


Note: If the CustomerContract and ConsumptionNotification dynamic fields have not been created automatically, they must be created in the environment.

This module can be configured via "System Configuration" in the administrative interface. The following configuration options are available:


Configuration to enable contract and services ACL. This ACL does not allow you to view services that are not associated with contracts. Remember that in CustomerPortal, the parent service must be associated with the contract to show the children.


Event that checks for expired contracts, if a ticket is created. It comes by default disabled:



Adds a custom time unit:




Ticket information shown in the ticket overview. ("TicketNumber" cannot be disabled as it is necessary).

Being 1 to enable the column and 0 to disable it, these are the default values:


Other customer user information is also available, which are:

  • CustomerUserCity: city of the customer user;

  • CustomerUserCountry: country of the customer user;

  • CustomerUserEmail: email of the customer user;

  • CustomerUserFirstname: first customer user name;

  • CustomerUserFullname: full name of the customer user;

  • CustomerUserLastname: last name of the customer user;

  • CustomerUserMobile: customer user's cell phone;

  • CustomerUserPhone: customer user's phone;

  • CustomerUserStreet: address of the customer user;

  • CustomerUserTitle: title of the customer user;

  • CustomerUserZip: postal code of the customer user.


Adds "Types" of calls that are not counted in the contracts (Use the "Types" in the "Type" menu).


The possible values ​​are the "Types" that are in the "Types" menu.


Time unit used by OTRS to calculate the time worked.

The available values ​​are hours and minutes, as shown in the image below:



These settings allow you to define the information needed to create the new notification ticket for expired contracts, as shown in the image below:



Enables notification for expired contracts.

Disabled by default.


Enable to list the company contracts if the client user is not associated with any contract.

Enable by default.


Configuration for the contract to become invalid after its expiration.

Disabled by default.


Enables the "Priority" field in the contract register.

Default value = disabled.


Enables the "Priority" field in the contract registration as mandatory.

Default value = disabled.


Enables the "SLA" field in the contract register.

Default value = disabled.


Enables the "SLA" field in the contract register as mandatory.

Default value = disabled.


Enables the "Type" field in the contract register.

Default value = disabled.


Enables the "Type" field in the contract record as mandatory.

Default value = disabled.


Creates a column on the contract management screen, which allows you to associate an "SLA" for each priority in the contract.

Default value = disabled.


Contract creation

After installing the module, an item will be created in the "Administration" menu, called "Contract Management":


Clicking on this item, the following screen will be presented:


In which the user can add a contract.

The "Name" field will define the name that will be displayed for this contract (Required).

The "Document Number" field will define a document number.

The "Customer ID" field will define which customer this contract will be valid for (Required).

The "Start / End of Contract" fields refer to how long the contract will be in effect.

The "Total Hours" field refers to the total hours that customers can use the contract.

The "Consumption" field can have three different values ​​(Required):

  • Monthly, changing only the time it will take to "reset" to 1 (one) month;

  • Project, it would only have the start and end time of the project to use the hours of the contract, not being "zeroed".

The "Validity" field can have three different values ​​(Required):

  • Invalid, in which the contract will not be used;

  • Temporarily invalid, in which the contract is invalid due to any alteration or change;

  • Valid, in which the contract is valid to be used;

The "Attachments" field saves the attachments related to these contracts.

Dynamic Fields

It is possible to add dynamic fields to the contract. For this it will be necessary to create a dynamic field of the contract type object. We currently recommend creating only standard OTRS objects (Checkbox, Date, Date / Time, Dropwown, multiselect, Text and Textarea).


When selecting the field below, a list with the dynamic fields of the contract object will be displayed. To add a field just click on the selection.



The field will be loaded just below, being possible to fill with the desired value.


It is possible to perform a mapping so that the values of the dynamic fields of the contract are filled in the dynamic fields of the ticket, for that it will be necessary to create a dynamic field of the same type for the called object and carry out the mapping in the configuration ContractManagement::Core::MappingContract4Ticket

Configure in such a way that the configuration key is the name of the dynamic field of the contract and in the value is the name of the dynamic field of the ticket that will be assigned the value.


With the mapping done, when opening a ticket with the selected contract or when associating a new contract, the dynamic fields that are configured above will be passed to the dynamic fields of the ticket.

Consumption notification

Before setting up contract notification, make sure that the dynamic field ConsumptionNotification exists in your environment. If not, create as follows:

|Name | Type | Object |

| -| -| -|

|ConsumptionNotification| Multiselect | Contract |

In the values follow this pattern:









After that it will be necessary to add events of the type called in the OTRS for each value filled in the dynamic field ConsumptionNotification. To do this, access the system settings and search for Events###Ticket

Add the event name as follows:


For each percentage value added in the dynamic field, an event will be required.


Dynamic field values ConsumptionNotification:


Registered events:


You can define consumption notifications for each contract. In contract management, the field below determines when notification events will be triggered.


In the ticket notification settings, select the events intended for the consumption of the contracts.


If the consumption of the contract reaches the configured percentage, the event will be triggered. With that all notifications or generic attendants that have in the events will be triggered.

Contract association to customer and service user

It is possible to associate contracts with client users and services.

Contract - Customer User

Access "Admin -> Contract - Customer User".

On the left side, all valid contracts will be listed. On the right side all client users.


If you click on a contract, you will be redirected to an association screen where all possible client users will be listed according to the client defined in the contract. If there is a customer user who is associated with the company through the Customer user - Customer list, it will also be listed.


Select the client users for this contract and save.

If you click on a client user, you will be redirected to a membership screen where all possible contracts for the selected user will be listed. If the user is associated with a company through the Customer user - Customer list, the contracts of the other company associated with him will also be listed.

Select the contracts for that customer user and save.

Contract - Service

Access "Admin -> Contract - Service".

On the left side, all valid contracts will be listed. On the right side all services.


If you click on a contract, you will be redirected to a membership screen where all the services to be associated will be listed.

Select the services for that contract and save.

If you click on a service, you will be redirected to a membership screen where all possible contracts for the selected service will be listed.

Select the contracts for that service and save.

On the opening screens or the screens where the contract field is enabled for editing, the contracts will be displayed as follows:

If there is no contract association with the client user, the module will list all the client contracts.

If there is an association of the client user with the contract, the display of the contracts will follow the associations made for the client user in question.


ABC company has the following contracts:

  • Contract 1

  • Contract 2

  • Contract 3

User john from company ABC is associated with the contracts:

  • Contract 2

  • Contract 3

The user john from the company ABC is associated with the services:

  • Service 1

  • Service 2

  • Service 3

The contracts have the following association with the services:

  • Contract 1

  • Service 1

  • Contract 2

  • Service 2

  • Contract 3

  • Service 1

  • Service 3

For opening tickets or if the ticket is already open with the following values:

Client user: john (company ABC)

Selected contract: Contract 3

The service field will allow the selection of service 1 or service 3

Example in the images below:

Company contracts:


Contracts associated with the user

Contracts that have been associated with the client user have the following service associations

In the opening screens (same operation for editing screens for tickets already created):


For each selected contract, the service field will be filtered according to the association of each contract.

Service Contract Preferences.

When associating a service contract, it is possible to create a customized service preference for that contract.

You will be redirected to the service change screen. Any changes on this screen will be saved in a preference for the selected Contract. When opening a ticket with the service and with the selected contract, OTRS will consider the values saved in the service according to this preference.

Checking hours consumption

An item will also be created, in the top menu of the tool, called "Contract", clicking on it will open the sub-menu "Consumption of Customer Hours":


The item "Customer List" will show a list with all customers (even if they do not have contracts), total hours consumed by them, total hours of the contract (s), consumption of these contracts in% (percentage) and details about tickets (covered in item):


The item "Filters" would be a search using the following parameters:

● Customer IDs: companies to be selected;

● Year: year in which the tickets were created;

● Month: month in which the tickets were created;


The "Actions" item shows contracts that expire in 30 days, 60 days and 90 days, it also has the button to return to the initial "Customer hours consumption" screen:


Checking hours consumption

When a call is opened for the client user, he can select his company's contract.

The ticket will be opened and the contract that the ticket is linked to will be in the left sidebar:


The attendant can add a new note counting the time:


Now with the contract being used, we are able to view consumption by going to the "Customer Hours Consumption" page.

As it was pointed out only 10 hours in the call, only 1% of the contract was used.

You can also have more specific information for each contract or for everyone by clicking on the magnifying glass icon in the Details column which will open the following screen:


That will show the contracts, the total of calls, the type of consumption, the total hours, the total consumed, balance and the column "Tickets" with the option to open another screen in which will show all calls related to this contract :


The contract consumption will also be available on the ticket screen (AgentTicketZoom), if there is a contract associated with the ticket, the widget with the contract consumption information will be displayed, showing the total hours of the contract and the percentage consumed in the month.


Expiration notification

If the contract has 30 days or less to expire, a ticket will be created automatically.

Note: the maturity was one more day because the end of the contract is on 10/26/2018 at 23:59:59.

For the notification to work correctly it is necessary to enable and configure the items below:

  • Daemon::SchedulerCronTaskManager::Task###ContractExpiration

  • ContractManagement::Core::ContractExpiration::NewTicketNo tification

  • ContractManagement::Core::ContractExpiration::Notification