Vizdum Support

Overview

Addition of any new services in Vizdum depends on the service provider itself.

Some providers offer OAuth integration while others offer simple API key and secret based HTTP Authentication. Every service which offers data through API provides tutorials and libraries to connect with their services. This tutorial emphasizes on where to place those libraries inside the code, how to use those libraries to fetch data from those services and store it inside the application’s No SQL data store (AWS Dynamo DB), and serve it through widgets inside any dashboard.

Mail Chimp Service Integration Example

In this section of the tutorial we will discuss the Mail Chimp Service integration.

Mail Chimp uses OAuth to communicate. Vizdum is built upon the Laravel framework, which provides a package called Socialite, see details at https://laravel.com/docs/5.0/authentication#social-authentication

Through Socialite, popular services like Facebook, Twitter and Github can be integrated using OAuth. 

How to integrate Mail Chimp service in Laravel

For Mail Chimp, socialite provider has been extended by a third party open source provider called socialiteproviders, see details given at http://socialiteproviders.github.io/providers/mailchimp/ 

Create an App at Mail Chimp and use it in Vizdum

After following the instructions from socialite providers, the service is almost ready to use, you need to register a development application at Mail Chimp using instructions provided at https://developer.mailchimp.com/documentation/mailchimp/guides/how-to-use-oauth2/

You will get a Client_ID and Client Secret which need to be added inside your .env file, present at the root of Laravel framework, /var/www/vizdum-self-hosted/vizdum_api and use those .env constants inside /var/www/vizdum-self-hosted/vizdum_api/config/services.php like 

'mailchimp' => [

        'client_id'        => env('MAILCHIMP_CLIENT_ID'),

        'client_secret' => env('MAILCHIMP_SECRET_KEY'),

        'redirect'         => env('API_BASE_URL').'/oauth2/callback',

    ]

Vizdum Database and Code Changes required for New Integrations

In this section we will talk about the application part.

Application categorizes different services in different categories, please for check categories in the database categories table. Mail chimp lies in the email category. If your required service has a new category, then you can add a category by using Laravel DB Seeds, (see details at https://laravel.com/docs/5.4/seeding), you can also find previous seed scripts inside /var/www/vizdum-self-hosted/vizdum_api/database/seeds directory 

In the next step you need to add the services inside app, by adding a new service in DB services table by using DB seeds. The service addition seeder script for Mail Chimp is already there.   

Next, add the mapping of services and Providers by seeders. After adding all necessary database entities, the last step is of implementation. 

As defined above, env('API_BASE_URL'). /oauth2/callback is the callback URL, which is called after authentication popup of the services is called and authentication is done. For external service, redirect app user is required to call back user with Auth data.You will need to register a provider which handles that callback and stores auth data in the DB provider table. You can register a new provider inside /var/www/vizdum-self-hosted/vizdum_api/app/Sdk/ProviderFactory.php 

The MailChimp driver is registered there as :

protected function createMailchimpDriver()

    {

        return $this->buildProvider(

            'VizdumApi\Sdk\Providers\MailChimpProvider'//, $config

        );

    }

Now you will need to write a provider class for the new service. For instance, the MailChimpProvider class is written at /var/www/vizdum-self-hosted/vizdum_api/app/Sdk/Providers/MailChimpProvider.php for MailChimp.

This class implements Provider contract and must implement the Contract methods. Also all API end points, API invocation methods, metadata methods, widget load methods must be implemented. 

Next, you will need to implement the 1st widget of your new service, just like the mailchimp_campaign_stats widget was implemented in the app.

You will need to add service and widget mapping inside the js file at the given path /var/www/vizdum-self-hosted /vizdum_wp_ng/wp-content/themes/Avada\dashboard/js/controllers/widget/WidgetWizardController.js.

After this step, add the DB details for your new widget record in widget_types table through the seeder.