@totvs/mingle
- @typescript: 3.2.2 or more
A typescript library to facilitate the communication of applications written in Javascript
with the server Mingle
.
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:
Using npm:
$ npm install --save @totvs/mingle
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
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:
this.mingleService.use(GeolocationPlugin);
this.mingleService.use(DevicePlugin);
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!');
});
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 => {
...
});
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.
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 { }
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');
}
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.
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()