dts-backoffice-util v16.1.0

Documentação dos Componentes e Utils

Objetivo

Biblioteca que engloba diversos componentes e serviços utilizados no desenvolvimento HTML/Angular com PO-UI.

Versões

Segue abaixo as últimas versões da Biblioteca, conforme a versão do PO-UI e Angular correspondentes.Detalhes das alterações: [VER CHANGE LOG](https://github.com/ModernizaDatasul/dts-backoffice-util/blob/master/projects/dts-backoffice-util/CHANGELOG.md).

Pré-Requisitos

Instalação do Pacote:

npm install dts-backoffice-util

Componentes e Serviços Disponíveis

TranslateService

Objetivo: Realizar o controle do idioma corrente, considerando o que estiver parametrizado no Cadastro de Usuários do Datasul, e caso não esteja informado, será considerado o idioma informado no Browse.

Importação:

import { TranslateService } from 'dts-backoffice-util';

Métodos:

dtsDateFormat

Objetivo: PIPE para formatar datas, ele foi criado pois o PIPE date do angular não consegue formatada datas inferiores a 1901.

Importação: No módulo de funcionalidade importar o módulo abaixo:

@NgModule({
    declarations: [
        ...
    ],
    imports: [
        ...,
        DtsBackofficeUtilsModule
    ],
    providers: [],
    bootstrap: [...]
})

Exemplo de uso:

<po-info p-label="Data"
    [p-value]="date | dtsDateFormat : 'dd/MM/yyyy'">
</po-info>

<po-info p-label="Data"
    [p-value]="date | dtsDateFormat : 'MM/dd/yyyy'">
</po-info>

MenuDatasulService

Objetivo: Interagir com o Menu do Datasul.

Importação:

import { MenuDatasulService } from 'dts-backoffice-util';

constructor(public menuDatasulService: MenuDatasulService) {
}

Métodos:

Exemplo de uso:

// Executando uma tela Progress
program = { 
  prg: 'bas_lote_liquidac_acr',
  params: [
    { type: 'character', value: 'ABC' },
    { type: 'integer', value: '345' }
  ]
};
this.menuDatasulService.callProgress(program);

// Executando uma Tela THF1
this.menuDatasulService.openTHF('dts/mab/activities', '', true);

// Executando uma Tela PO-UI
this.menuDatasulService.openPath('html.creditCardOperator', '1509;10;1', true);

// Disparando uma Notificação
notification = { 
  type: 'success',
  title: 'Operação foi executada com Sucesso.',
  detail: 'A Operação 4343 foi executada conforme parametrizado e finalizou.'
};
this.menuDatasulService.sendNotification(notification);

// Validando a Segurança de um Programa
this.menuDatasulService
  .programSecurity('html.cashControl')
  .subscribe((response: Array<Object>) => {
    console.log('response:', response[0]);
    // Resposta: { programName: "html.cashControl", hasAccess: true }
});

// Validando a Segurança de uma Lista de Programas
let programList = [];
programList.push('pr0590');
programList.push('html.prgNoExist');
programList.push('bas_empresa');

this.menuDatasulService
  .programSecurity(programList)
  .subscribe((response: Array<Object>) => {
    console.log('response:', response);
    /* Resposta:
       [
         0: { programName: "pr0590", hasAccess: false }
         1: { programName: "html.prgNoExist", hasAccess: false }
         2: { programName: "bas_empresa", hasAccess: true }
       ] */
});

TotvsScheduleExecutionComponent

Objetivo: Componente para realização de agendamentos RPW.

Dependências: Para usar esse componente deve ser instalado no projeto o pacote rxjs-compat.

• npm i rxjs-compat --save

Importação: No módulo da aplicação importar o módulo abaixo:

@NgModule({
    declarations: [
        ...
    ],
    imports: [
        ...,
        DtsBackofficeUtilsModule.forRoot()
    ],
    providers: [],
    bootstrap: [...]
})

Parâmetros:

Métodos:

Exemplo de Uso:

Em conjunto com o parâmetro endExecution o método setScheduleParameters pode ser utilizado para salvar e recuperar as informações de agendamento informadas pelo usuário.

Definições no HTML:

// EXEMPLO PARA EMS5
<app-totvs-schedule-execution #schParam
  programName="rpt_grp_repres"
  externalName="rpt_grp_repres"        
  programEMS5="true"
  programStyle="40"
  programVersion="1.00.00.004"
  [parameters]="parametersRpw"
  [paramSelections]="paramSelectionsRpw"
  (endExecution)="endExecutionSchedule($event)">
</app-totvs-schedule-execution>

// EXEMPLO PARA EMS2
<app-totvs-schedule-execution #schParam
  programName="pdapi701"
  externalName="pdp/pdapi701.p"
  [parameters]="parametersRpw"
  [paramDigitDef]="paramDigitDefRpw"
  [paramDigitData]="paramDigitDataRpw"
  (endExecution)="endExecutionSchedule($event)">
</app-totvs-schedule-execution>    

Definições no JavaScript:

@ViewChild('schParam', { static: true }) schParam: TotvsScheduleExecutionComponent;

scheduleParams: IScheduleParameters;
parametersRpw = new Array<any>();
paramDigitDefRpw = new Array<any>();
paramDigitDataRpw = new Array<any>();
paramSelectionsRpw = new Array<any>();

ngOnInit(): void {
  this.loadLocalStorage();
  this.schParam.setScheduleParameters(this.scheduleParams);

  this.createParametersRpw();
}

createParametersRpw(): void {
  // Parâmetros
  this.parametersRpw = [
    { chave: 'destino', valor: 2, tipo: 'integer' },
    { chave: 'arquivo', valor: '', tipo: 'character' },
    { chave: 'usuario', valor: 'FERNANDO', tipo: 'character' },
    { chave: 'perfil', valor: 880, tipo: 'integer' }
  ];

  // Definição da tt-digita (EMS2)
  this.paramDigitDefRpw = [
    { chave: 'cod-estab', tipo: 'character' },
    { chave: 'cod-ccusto', tipo: 'integer' }
  ];

  // Dados da tt-digita (EMS2)
  this.paramDigitDataRpw = [
    { "cod-estab": '19', "cod-ccusto": 17 },
    { "cod-estab": '28', "cod-ccusto": 11 },
    { "cod-estab": '73', "cod-ccusto": 90 }
  ];

  // Seleção (Relatório Regra/Exceção do EMS5)
  this.paramSelectionsRpw = [
    { ind_dwb_set_type: "Regra", cod_dwb_set: "estab",
      cod_dwb_set_initial: "01", cod_dwb_set_final: "FF", log_dwb_rule: true },
    { ind_dwb_set_type: "Exceção", cod_dwb_set: "ccusto",
      cod_dwb_set_initial: "30", cod_dwb_set_final: "35", log_dwb_rule: false }
  ]
}

endExecutionSchedule(event): void {
  this.scheduleParams = event;
  this.saveLocalStorage();
}

private saveLocalStorage(): void {
  if (typeof (Storage) === 'undefined') { return; }
  localStorage.setItem('param-maint.schParam', JSON.stringify(this.scheduleParams));
}

private loadLocalStorage(): void {
  if (typeof (Storage) === 'undefined') { return; }
  this.scheduleParams = JSON.parse(localStorage.getItem('param-maint.schParam'));
}

Definições no Progress:

DEFINE TEMP-TABLE tt-param NO-UNDO
  FIELD destino AS INTEGER
  FIELD arquivo AS CHARACTER
  FIELD usuario AS CHARACTER
  FIELD perfil  AS INTEGER.

DEFINE TEMP-TABLE tt-digita NO-UNDO
  FIELD cod-estab  AS CHARACTER
  FIELD cod-ccusto AS INTEGER.

Interfaces:

IScheduleParameters | Nome | Tipo | Descrição | Valor - Label Valor | |-|-|-|-| | executionType | number | Tipo Execução | 1 - Executar Hoje2 - Agendar Execução | | execAppointDate | date | Data Agendada | | | execAppointHour | string | Hora Agendada | | | executionServer | string | Servidor RPW | | | repeatExecution | boolean | Repetir Ocorrência | | | repeatType | number | Tipo Repetição | 1 - Diária2 - Semanal3 - Mensal | | frequency | string | Frequência | "no" - Uma vez no dia"yes" - Várias vezes no dia | | frequencyValue | number | Quantidade da Frequência | | | frequencyType | string | Tipo Frequência | "hour" - Hora(s)"minute" - Minuto(s) | | execAppointHourInit | string | Hora Inicial Frequência | | | execAppointHourFinal | string | Hora Final Frequência | | | selectWeeklys | Array | Dia da SemanaFrequência Semanal | Sunday - DomingoMonday - SegundaTuesday - TerçaWednesday - QuartaThursday - QuintaFriday - SextaSaturday - Sábado | | dayOfMonth | number | Dia do MêsFrequência Mensal | |

TotvsScheduleExecutionService

Objetivo: Serviço que disponibiliza métodos para geração de agendamento e acompanhamento do RPW.

Métodos:

Exemplo de Uso:

Segue abaixo exemplos da geração de agendamento, busca e acompanhamento da execução.

Definições no HTML:

<po-lookup
  p-label="Servidor RPW"
  p-placeholder="Servidor RPW"
  [p-columns]="zoomRpwServiceColumns"
  [p-field-format]="fieldRpwServiceFormat"
  [p-filter-service]="scheduleExecution"
  p-field-label="name"
  p-field-value="code"
  [(ngModel)]="executionServer">
</po-lookup>

Definições no JavaScript:

executionServer: string;
jobScheduleID: string;
executionID: string;
execStatus: string;

zoomRpwServiceColumns: Array<PoLookupColumn> = [
  { property: 'code', label: 'Servidor', type: 'string', width: '20%' },
  { property: 'name', label: 'Descrição', type: 'string', width: '80%' }
];

private schedExecSubscription$: Subscription;

constructor(
  ...
  public scheduleExecution: TotvsScheduleExecutionService
}

fieldRpwServiceFormat(value) {
  return `${value.code} - ${value.name}`;
}

createSchedule(): void {

  // Criar um Agendamento para ser Executado "agora"
  const execParam = new ExecutionParameters();
  execParam.executionServer = executionServer;

  // Exemplo de Parâmetros para o EMS5
  execParam.programName = 'rpt_grp_repres';
  execParam.externalName = 'rpt_grp_repres';
  execParam.programEMS5 = true;
  execParam.programStyle = 40;
  execParam.programVersion = '1.00.00.004';
  execParam.businessParams = [
    { chave: 'cTipoCarga', valor: 'register', tipo: 'character' },
    { chave: 'lCargaTotal', valor: false, tipo: 'logical' },
    { chave: 'dDataCorte', valor: null, tipo: 'date' }
  ];
  // Seleção (Relatório Regra/Exceção do EMS5)
  execParam.paramSelections = [
    { ind_dwb_set_type: "Regra", cod_dwb_set: "estab",
      cod_dwb_set_initial: "01", cod_dwb_set_final: "FF", log_dwb_rule: true },
    { ind_dwb_set_type: "Exceção", cod_dwb_set: "ccusto",
      cod_dwb_set_initial: "30", cod_dwb_set_final: "35", log_dwb_rule: false }
  ];

  // Exemplo de Parâmetros para o EMS2
  execParam.programName = 'pdapi701';
  execParam.externalName = 'pdp/pdapi701.p';
  execParam.businessParams = [
    { chave: 'destino', valor: 2, tipo: 'integer' },
    { chave: 'arquivo', valor: '', tipo: 'character' },
    { chave: 'usuario', valor: 'FERNANDO', tipo: 'character' },
    { chave: 'perfil', valor: 880, tipo: 'integer' }
  ];
  // Definição da tt-digita (EMS2)
  execParam.paramDigitDef = [
    { chave: 'cod-estab', tipo: 'character' },
    { chave: 'cod-ccusto', tipo: 'integer' }
  ];
  // Dados da tt-digita (EMS2)
  execParam.paramDigitData = [
    { "cod-estab": '19', "cod-ccusto": 17 },
    { "cod-estab": '28', "cod-ccusto": 11 },
    { "cod-estab": '73', "cod-ccusto": 90 }
  ];

  this.schedExecSubscription$ = this.scheduleExecution
    .createExecutionForNow(execParam, true)
    .subscribe((response: any) => {

      // Guarda o ID do Agendamento para fazer o acompanhamento
      this.jobScheduleID = response.jobScheduleID;
    });
}

getExecution(type: string): void {

  if (type === 'jobScheduleID') {
    this.schedExecSubscription$ = this.scheduleExecution
      .getExecutionByJobScheduleID(this.jobScheduleID, true)
      .subscribe((response: IExecutionStatus) => {

        if (response) {
          // Guarda o Número do Agendamento e o Status
          this.executionID = response.executionID;
          this.execStatus = response.status;
        } else {
          this.executionID = 'Não Encontrado !';
          this.execStatus = '';
        }
      });
  }

  if (type === 'executionID') {
    this.schedExecSubscription$ = this.scheduleExecution
      .getExecutionByExecutionID(this.executionID, true)
      .subscribe((response: IExecutionStatus) => {

        if (response) {
          // Guarda o ID interno do Agendamento e o Status
          this.jobScheduleID = response.jobScheduleID;
          this.execStatus = response.status;          
        } else {
          this.jobScheduleID = 'Não Encontrado !';
          this.execStatus = '';
        }
      });
  }
}

followUp(type: string): void {

  if (type === 'jobScheduleID') {
    // Inicia o Acompanhamento
    this.scheduleExecution.followUpExcByJobScheduleID(this.jobScheduleID, 5000, this.followUpCallBack.bind(this));
  }

  if (type === 'executionID') {
    // Inicia o Acompanhamento
    this.scheduleExecution.followUpExcByExecutionID(this.executionID, 5000, this.followUpCallBack.bind(this));
  }
}

followUpCallBack(execStatus: IExecutionStatus): boolean {
  // Verifica o Status do Agendamento
  switch (execStatus.status) {
    case 'PENDING': // Ainda não iniciou

      console.log('Esta esperando para executar...');
      break;

    case 'RUNNING': // Em execução

      console.log('Esta rodando...');
      break;

    case 'SUCCESS': // Terminou OK

      console.log('Terminou OK...');
      break;

    case 'FAILURE': // Terminou com Erro

      console.log('Terminou com o erro:', execStatus.error);
      break;
  }

  return true; // Continua monitorando - retornar "false" para parar o monitoramento
}

Definições no Progress:

DEFINE TEMP-TABLE tt-param NO-UNDO
  FIELD destino AS INTEGER
  FIELD arquivo AS CHARACTER
  FIELD usuario AS CHARACTER
  FIELD perfil  AS INTEGER.

DEFINE TEMP-TABLE tt-digita NO-UNDO
  FIELD cod-estab  AS CHARACTER
  FIELD cod-ccusto AS INTEGER.

Interfaces:

IExecutionParameters | Nome | Tipo | Obrigatório | Descrição | |-|-|-|-| | executionServer | string | Sim | Código do Servidor RPW. | | programName | string | Sim | Código de Programa cadastrado no menu, do programa que será executado no RPW. | | externalName | string | Sim | Nome completo do Programa que será executado no RPW, diretório + nome externo.Importante: Em virtude do dicionário (Foundation), este parâmetro é limitado a 24 dígitos. | | programEMS5 | boolean | Não | Indica se o programa progress é do EMS5. | | programStyle | number | Não | Número que representa o Estilo do Relatório no EMS5. | | programVersion | string | Não | Versão do programa progress. | | businessParams | Array | Não | Objeto representando a Temp-Table que será enviada ao progress. | | paramDigitDef | Array | Não | Definição da Temp-Table tt-digita. Utilizado apenas pelo EMS2. Para cada campo da tt-digita, deve ser enviado um objeto com o seguinte formato: {"chave": "string", "tipo": "string" }. Onde chave representa o nome do campo, e tipo representa o tipo de dado (exemplo: character, integer, etc...). | | paramDigitData | Array | Não | Dados que serão enviados e alimentados na tt-digita. Utilizado apenas pelo EMS2. | | paramSelections | Array | Não | Parâmetros de Seleção. Utilizado apenas pelo EMS5. |

IExecutionStatus | Nome | Tipo | Descrição | |-|-|-| | jobScheduleID | string | ID Interno do Agendamento. | | executionID | string | Número da Agenda (código da execução). Pode ser utilizado para, por exemplo, apresentar ao usuário, assim ele pode realizar a consulta dos detalhes da execução através do Monitor de Pedido de Execução (programa padrão do Foundation). | | startedDate | Date | Data e hora em que o agendamento iniciou a execução no RPW. | | error | string | Quando o status for igual a 'FAILURE', esta propriedade terá a descrição do erro. | | status | string | Status da execução, podendo ser:- PENDING: O agendamento está enfileirado, aguardando o início da execução.- RUNNING: O agendamento está em execução.- SUCCESS: O agendamento terminou corretamente, sem erros.- FAILURE: O agendamento terminou com erro. A descrição do erro estará disponível na propriedade error. Observação: Caso não exista um agendamento com o ID informado, também será retornar este status de erro. |

ProfileService

Objetivo: Salvar preferências do usuário.

Importação:

import { ProfileService, IProfile } from 'dts-backoffice-util';

constructor(public preferenceService: ProfileService) {
}

Métodos:

Interfaces:

IProfile | Nome | Tipo | Obrigatório | Descrição | |-|-|-|-| | pageId | string | Sim | Um ID para identificar a Tela que está salvando os parâmetros. | | userCode | string | Sim | Código do usuário (login). | | dataCode | string | Sim | Um ID para identificar o parâmetro. |

| dataValue | string | Não | Valor a ser salvo, nos GET's é opcional. |

Exemplo de Uso:

const profile: IProfile = {
  pageId: 'about-component',
  userCode: 'super',
  dataCode: 'preference',
  dataValue: this.preference
};

this.preferenceService
  .setProfile(profile)
  .subscribe((response) => {
  this.notification.success('Preferência salva com sucesso!');
}, (error) => {
  this.notification.error('Não foi possível salvar a preferência');
});

UserLoginService

Objetivo: Retorna o login do usuário tanto no framework atual e quanto no novo framework.

Importação:

import { UserLoginService } from 'dts-backoffice-util';

constructor( public sessionService: UserLoginService) {
}

Métodos:

Exemplo de Uso:

this.sessionService
  .getUserLogin()
  .subscribe((user) => {
  this.notification.success(`O usuário logado é ${user}`);
});

ReportService

Objetivo: Faz a chamada do datasul-report e realiza o download do arquivo caso seja especificado.

Importação:

import { 
  ReportService, 
  IReportServiceParams, 
  ReportFormats
} from 'dts-backoffice-util';

constructor(public reportService: ReportService) {
}

Métodos:

Interfaces:

IReportServiceParams

IProperty

Enums

declare enum ReportFormats {
    XLSX = "xlsx",
    PDF = "pdf",
    DOCX = "docx",
    HTML = "html"
}

Exemplo de Uso:

const properties: Array<IProperty> = [
  { 
    name: 'custom.quick_search', 
    value: '186'
  }
];

const params: IReportServiceParams = {
  reportName: 'crm/rel_campaign_export',
  programName: '/report/crm/crm0010',
  properties,
  dialect: 'pt',
  download: true,
  downloadName: '2020-1-10_13-51-53_CRM_CAMPANHAS',
  format: ReportFormats.XLSX
};

this.reportService
  .generate(params)
  .subscribe(() => {
  this.notification.error("Arquivo baixado com sucesso!");
}, () => {
  this.notification.error("Não foi possível baixar o arquivo");
});

BreadcrumbControlService

Objetivo: Realiza a criação e controle do breadcrumb das telas.

Importação:

import { BreadcrumbControlService } from 'dts-backoffice-util';

Métodos:

DateUtil

Objetivo: Manipula informações de data.

Importação:

import { DateUtil } from 'dts-backoffice-util';

Métodos:

FileUtil

Objetivo: Auxílio na manipulação de Arquivos.

Importação:

import { FileUtil } from 'dts-backoffice-util';

Métodos:

Exemplo de Uso:

Definições no JavaScript:

// TS da Tela

import { FileUtil } from 'dts-backoffice-util';

fileBase64: string;

downloadFile() {
  this.servCustomerSubscription$ = this.servCustomer
    .getFile('1') // Código do cliente 1
    .subscribe((response: Object) => {

      FileUtil.downloadFile(response['content'], response['filename']);
    });
}

downloadQrCode() {
  this.servCustomerSubscription$ = this.servCustomer
    .getQrCode('00020126360014BR.GOV.BCB.PIX0114+554798402310452040000530398654071500.005802BR5916Robervaldo6009Joinville62070503Novo%20QR%20pix63047EF5') // Texto Exemplo para Geração do QrCode
    .subscribe((response: Blob) => {

      FileUtil.downloadFile(response, 'qrCode.png', '', false);
  });
}

downloadList() {
  this.servCustomerSubscription$ = this.servCustomer
    .query([], [], 1, 999) // Método padrão de Query do Serviço de Cliente
    .subscribe((response: TotvsResponse<ICustomer>) => {

      const dwldDataParam = new DownloadDataParams();
      dwldDataParam.fileName = 'clientes.csv';
      dwldDataParam.columnDelimiter = ';';
      dwldDataParam.literals = this.literals;
      dwldDataParam.columnList = ['shortName', 'name', 'country', 'status', 'tax'];

      FileUtil.downloadData(response.items, dwldDataParam);
  });
}

onConfirmUpload(): void {
  // fileToSend: variável utilizada no ngModel do componente de Upload
  if (!this.fileToSend || this.fileToSend.length < 1) { return; }

  // fileBase64: variável do programa para receber o conteúdo em Base64
  FileUtil.fileToB64(this.fileToSend[0].rawFile).then(
    (data: string) => this.fileBase64 = data
  );
}

// TS do Serviço

getFile(id: string): Observable<Object> {
  const url = `/customer/${id}/file`;
  return this.http.get(url);
}

getQrCode(text: string): Observable<Blob> {
  const url = `/qrcode/download?text=${text}`;
  return this.http.get(url, { responseType: 'blob' });
}

Definições no Progress:

// Conteúdo do Método que BackEnd que retorna o Arquivo em Base64
DEFINE VARIABLE v_dir_arq AS CHARACTER NO-UNDO.
DEFINE VARIABLE v_cod_arq AS CHARACTER NO-UNDO.
DEFINE VARIABLE v_mtr_arq AS MEMPTR    NO-UNDO.
DEFINE VARIABLE v_lch_arq AS LONGCHAR  NO-UNDO.

ASSIGN v_dir_arq = "\\arpoador\Publico\"
       v_cod_arq = "layout_pagfor Sistema DDA.pdf".

COPY-LOB FROM FILE STRING(v_dir_arq + v_cod_arq) TO v_mtr_arq.
ASSIGN v_lch_arq = BASE64-ENCODE(v_mtr_arq).

oOutput = NEW JsonObject().
oOutput:ADD("filename", v_cod_arq).
oOutput:ADD("content",  v_lch_arq).

Interfaces:

IDownloadDataParams

DisclaimerUtil

xxxx

FieldValidationUtil

xxxx

FilterRangeUtil

xxxx

GenericFunctionsUtils

xxxx