@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:

$3

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:

`js
// 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:
` js
config.modules.web = true;
``

For a mobile application:
` js
config.modules.web = false;
``

Create an instance of the MingleService and configure: (DEPRECATED)
` js
const config = new Configuration();
config.app_identifier = 'your_app_id';
config.server = mingleService.servers.development;
config.modules.crashr = true;
config.modules.usage_metrics = true;
config.modules.push_notification = true;
config.modules.ocr = true;
config.modules.web = true;

this.mingleService.setConfiguration(config);
`

Create an instance of the MingleService and initalize:
` js
const server = mingleService.servers.development;
const appId = 'your_app_id';
const web = true;
this.mingleService.init(server, appId, web);
`

If you want to use aditional plugins:

$3

` js
this.mingleService.use(GeolocationPlugin);
`


$3

` js
this.mingleService.use(DevicePlugin);
`

$3

After this, create a instance:
` js
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:
` js

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:
`js
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 {
  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 = [
{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()
`js
// return token of authentication generated by login.
// type: String
this.mingleService.getAccessToken();
`

configMingleURL()
`js
// 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()
`js
// get url refresh token api.
// return url http://localhost/api/api/v1/auth/app/refresh
// type: String
this.mingleService.getRefreshTokenURL()
`

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

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

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