@totvs/mingle
v0.0.1-20241029.1
Published
Mingle core - client of Mingle
Downloads
315
Maintainers
Keywords
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: (DEPRECATED)
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:
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:
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 inset
:
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()