Skip to main content

Contact reports

This module adds a centralized contact-report system to your Qore application. Fully configurable to be used with your (custom) resources.

Installation​

warning

This module relies on the Qore/CRM module and will not work without it being in your Qore application.

To install this module:​

composer require qore/contact-reports

After you installed the module publish it's contents to your Qore application.

php artisan vendor:publish --tag=qore.contact-reports.config
php artisan vendor:publish --tag=qore.contact-reports.db
php artisan vendor:publish --tag=qore.contact-reports.frontend

After you have published the contents of the module be sure to run the migrations.

php artisan tenants:migrate

Initial setup​

After you have installed the module you need to enable it in your Qore application.

Settings​

Upon enabling the module, you can go to the settings of the module, here you can start to configure which data can be related to a contact report.

warning

It is important to note that a communication channel does not require a related resource to function.

What does this setting do?

This setting allows you to make dynamic relationships for your communication channels to other parts of the application. If a relationship is selected, on the create/edit page you will see a new field pop up once you select the communication channel. This will then allow you to select which resource needs to be bound to your contact report.

By default, you will be presented with 5 rows here. This can be expanded further if you require more communication channels. See Managing communication channels for more information.

Configuring the setting​

Each row you see represents a communication channel and its relation to different parts of your application.

First you will need to select one of the communication channels, and choose a resource that should be bound to that communication channel. Once that has been selected two more columns will pop up - here you can select what relationship you have to your organization/contact. At least one of these needs to be filled in order for the relationship to be resolved.

info

You are free to select any resource in the current application, as long as the resource has a direct relationship to either a contact or organization from the CRM module.

The relationships currently supported are BelongsTo and MorphTo — for both the contact and organization models.

What does this setting do?​

This setting like the setting above, allows you to bind different resources to a contact report. This setting however, is more flexible. It allows you to simply select the resource(s) that you would like to bind to your contact reports. Once you have chosen your resource(s) you will see multiple new rows on your create/edit pages. Allowing you to select the items that are related to the selected organization.

This setting will also automatically show up on the related resource. Adding a tab on the details page of the related resource which shows all related contact reports to that resource.

Configuration the setting​

To configure this setting simply select as many resources as you want from the dropdown.

If a resource is not present in the dropdown menu, it means that it does not have a direct relationship to an organization and cannot be used here.

info

An example of how this is intended to be used:

Imagine someone sends you an email enquiring about an invoice that was sent to them.
If your system includes a resource that manages these invoices — and this resource has a direct relationship to your organization — you can simply select it in the module settings.

Then, when creating a contact report, all invoices related to the selected organization will automatically be shown,
and you’ll be able to select as many as needed.

Managing communication channels​

Perhaps you have additional communication channels that you would like to add, or you need to disable a communication channel. This is made possible by changing the Application variables for the current tenant.

This setting can be found under Application -> Variables -> Contact report channel types

What is the end result?​

The intended end result of this chapter is to show an attach button and/or a tab on the detail page of the resource that has been related to a communication channel using the settings. This button will allow you to fill in a pre-filled form filled with the data gathered from the related resource.

warning

You need to have the same resource selected in your contact reports module settings for this to work. Without this relation being set in the settings of the contact reports module it is not possible for the attach button to actually bind to the related communication channel resource.

setting up the model​

For both the attach button as well as the tabs showing the related contact reports you will need to have a relationship defined in the model of the related resource.

public function contactReport(): MorphMany
{
    return $this->morphMany(ContactReport::class, 'bound_channel', 'bound_channel_type', 'bound_channel_id', 'id');
}

The next thing we need is to add a field to the field collection of your related resource.

if (module_is_active('qore/contact-reports')) {
    $fieldCollection->push(MorphMany::make(__('cr::cr.Contact reports'), 'contactReport', ContactReportsResource::class)
        ->onlyOnShow()
        ->withAttachButton()
        ->preventFill()
        ->withRelationalMeta(function (FormState $state) use ($that) {
            $relatedResourceModel = $state->getRelatedModel();
            if (! $relatedResourceModel instanceof relatedModel) {
                return;
            }
               
            /** @TODO Set the states of the form here */
            
        })
        ->asCard()
        ->asTab()
    );
}

The following helper functions should be setup depending on your needs:

One of the following helper functions needs to be called as this field should not be shown on the actual forms.

->onlyOnShow()
->onlyOnIndex()
->hideOnForms()

If you would like to see an overview of all related contact reports on the detail page you add

->asCard()
->asTab()

The withAttachButton() adds a button where you can add a contact report directly from the related resource detail page. This will also require you to configure the relational meta of the field. This makes sure that the data is prefilled when the form is opened.

->withAttachButton()
->withRelationalMeta(function (FormState $state) use ($that) {
    $relatedResourceModel = $state->getRelatedModel();
    if (! $relatedResourceModel instanceof relatedModel) {
        return;
    }
       
    /** @TODO Set the states of the form here */
    
})

Setting the states​

Most states are easy enough and follow the following pattern. Where you simply have to replace 'organization' with the field you want to set a state for.

$state->setState('organization', $relatedResourceModel->organization_id);
$state->readonlyFields('organization'); // If you do not want the user to be able to edit the field.
tip

To view all of the fields that you can set states for you can dd() the FormState in the withRelationalMeta() method.

tip

If you have a contact but not an organization you can still set the organization state by getting it from the contact's relation.

However, the related channel is a little different and will require a bit more tinkering to get working.

if (!$yourChannel = tenant_variable_value('Contact report channel types', 'yourChannel')) {
    return;
}

$setting = setting('qore/contact-reports', "bound_channel_resource_{$yourChannel->id}");

$state->setState('channel', $yourChannel->id);

$field = "boundChannel_$yourChannel->id";

$state->setState(
    $field,
    ['type' => $setting, 'id' => $relatedResourceModel->id]
);

$state->readonlyFields('channel');
$state->readonlyFields($field);

Firstly you need to get the correct tenant variable value. This can be one of you own tenant variables that you added as well as long as you know the name of the tenant variable. to find what you need to replace 'yourChannel' with you can find all of the possible values in the Application settings.

Under Application->Variables->Contact report channel types->Values

If you did not add any of your own the standard values are "note", "phone", "email", "whatsapp" and "appointment".

if (!$yourChannel = tenant_variable_value('Contact report channel types', 'yourChannel')) {
    return;
}

Next up you will need to get the setting related to your channel and set the state of the 'channel' field.

$setting = setting('qore/contact-reports', "bound_channel_resource_{$yourChannel->id}");

$state->setState('channel', $yourChannel->id);
tip

If this does not return anything make sure that you have set a relationship for the channel in the contact reports module settings

Lastly we just need to get the field and set the state for that field, which is easy enough as it is directly related to the id of your channels tenant variable.

$field = "boundChannel_$yourChannel->id";

$state->setState(
    $field,
    ['type' => $setting, 'id' => $relatedResourceModel->id]
);
info

You can of course also lock these two fields by simply adding the following lines

$state->readonlyFields('channel');
$state->readonlyFields($field);
warning

If you followed all of these steps but still don't have it working correctly make sure to set the states in the following order As each of these fields is dependant on each other.

Organization -> contact -> channel -> boundChannel_$id -> any other field