README

@TOTVS/MINGLE

Versions Dependencies

@totvs/mingle

@typescript: 3.2.2 or more

What's this?

A typescript library to facilitate the communication of applications written in Javascript with the server Mingle.

How to use?

To start using Mingle, the first thing to do is to install the necessary package for its operation. Run the following command in the folder of your project:

Installation

Using npm: $ npm install --save @totvs/mingle

Mingle with Ionic Application

To use Mingle in an Ionic application you must run the following commands to install the plugins used:

Mingle Ionic Device $ npm install --save @totvs/mingle-ionic-device
Geolocation $ npm install --save @totvs/mingle-ionic-geolocation
OCR ionic cordova plugin add cordova-plugin-file-transfer $ npm install --save @totvs/mingle-ionic-ocr

Configuration

In the application's app.component.ts file, import the classes and create a instance:

// using ES6 modules
import { MingleService } from @totvs/mingle;
private mingleService = new MingleService();

// using CommonJS modules
var mingle = require('@totvs/mingle')
var mingleService = new mingle.MingleService();

For a web application:

config.modules.web = true;

For a mobile application:

config.modules.web = false;

Create an instance of the MingleService and configure:

const config = new Configuration();
config.app_identifier = 'your_app_id';
config.environment = 'DEV';
config.server = 'https://mingle_server/api';
config.modules.crashr = true;
config.modules.usage_metrics = true;
config.modules.gateway = true;
config.modules.push_notification = true;
config.modules.ocr = true;
config.modules.web = true;

this.mingleService.setConfiguration(config);

If you want to use aditional plugins:

Geolocation

this.mingleService.use(GeolocationPlugin);

Device Ionic Plugin

this.mingleService.use(DevicePlugin);

OCR

After this, create a instance:

const ocr = new OcrPlugin(this.mingleService);
ocr.readBusinessCard({}, this.mingleService);

Now everything is ready, lets use in application.

The first thing to do is to initialize Mingle, and verify that the user is already authenticated:


this.mingleService.auth.login('admin', 'admin', 'alias sufix').subscribe(() => {
this.mingleService.registerMetric('APP_INIT');
console.log('Sign in ok');

}, (authError) => {

console.log('Authentication Error: User or password invalid!');

});

Gateway

it is the responsibility of the developer to inform the headers required for the gateway service. The mingle provides a method to obtain the parameters registered in SET.

Sample tenantid - Protheus value default in set:

const paramsSet = this.mingleService.getParams();

const company = paramsSet.filter(e => e.key === 'EMPRESA').map(e => e.value);
const branch = paramsSet.filter(e => e.key === 'FILIAL').map(e => e.value);
const options = {headers: {tenantid: `${company + ',' + branch}`}};

this.mingleService.gateway.get(url, options, params).subscribe(response => {
...
});

Http Interceptor

Mingle also provides a class called MingleHttpInterceptor that functions as a request interceptor.

The purpose of this interceptor is that any http call made by the app using only the / api / customers feature will automatically be added in the request to the mingle url, and the Authorization (token), Content-Type and tenantId headers.

Angular sample

To use the MingleHttpInterceptor, just set in the app.module.ts:

import { MingleHttpInterceptor } from '@totvs/mingle';
import { HTTP_INTERCEPTORS } from '@angular/common/http';

Add in providers section:

@NgModule({
declarations: [
AppComponent,
DashboardComponent,
HomeComponent
],
imports: [
BrowserModule,
HttpClientModule,
RouterModule.forRoot(routes)
],
providers: [MingleService,
{
provide: HTTP_INTERCEPTORS,
useClass: MingleHttpInterceptor,
multi: true,
}],
bootstrap: [AppComponent]
})
export class AppModule { }

RXJS

We always work with the stable version of rxjs package.

Your application can be in any version of rxjs, because we package it in a way that Mingle uses its own version, ignoring that of the application.

We provide an object to type methods in the version of RXJS that Mingle uses:


import { MingleObservable } from '@totvs/mingle';

myMethod(): MingleObservable<any> {
  return this.mingleService.gateway.get('endpoint');
}

Set custom headers

After login, it is possible to set headers for gateway requests. for example:

  this.mingleService.auth.login('user', 'password', 'prefix suffix')
  .subscribe(res => { 

    const paramsSet = this.mingleService.getParams();

    if (paramsSet) {
      const company = paramsSet.filter(e => e.key === 'EMPRESA').map(e => e.value);
      const branch = paramsSet.filter(e => e.key === 'FILIAL').map(e => e.value);

      const defaultHeaders: Array<HeaderOption> = [
        {name: 'tenantid',  value: `${company + ',' + branch}`}, 
        {name: 'X-CUSTOMER', value: 'customer'}
      ];

      this.mingleService.setDefaultHeaders(defaultHeaders);
    }

  });

this sample adds the headers: X-CUSTOMER and tenantid to every gateway request.

Public methods

getAccessToken()

  // return token of authentication generated by login.
  // type: String
  this.mingleService.getAccessToken();

configMingleURL()

  // config URL to gateway.
  // @param: endpoint ex: check_security
  // return url configured ex: http://localhost/api/api/v1/gateway/your_set/check_security
  // type: String
  this.mingleService.configMingleURL('check_security');

getRefreshTokenURL()

  // get url refresh token api.
  // return url http://localhost/api/api/v1/auth/app/refresh
  // type: String
  this.mingleService.getRefreshTokenURL()

getBodyToRefreshTokenAPI

  // get body to refresh token API.
  // return object to post in refresh token API.
  // type: String
  this.mingleService.getBodyToRefreshTokenAPI()

setTokenInSession

  // set new token in session of Mingle
  // @param: token - string
  // type: String
  this.mingleService.setTokenInSession()

getSessionInfo

  // return object with infos of session
  // type: Object
  this.mingleService.getSessionInfo()

Usage no npm install needed!