API de Envio de compromisso via Outlook (001)

Nome Físico: utp/utapi028.p

Nome do Include com Parâmetros: utp/utapi028.i

Versão de Integração: 001

Objetivo: 

Envio de compromisso do tipo reunião via Microsoft Outlook.

Pré-requisitos: 

É necessário ter o OUTLOOK com uma versão compatível com o produto. Para mais detalhes consulte a documentação localizada em: https://tdn.totvs.com/pages/releaseview.action?pageId=195301010





Considerações Gerais

  • A API recebe como parâmetros valores que correspondem as informações necessárias para envio do compromisso;
  • A include {utp/utapi028.i} contém as definições das Temp-Tables que devem ser passadas como parâmetros à API utp/utapi028.p. Sendo que a chamada desta include, como a inclusão de valores, deve ser feita antes da chamada da API utp/utapi028.p;O envio do compromisso é feito através da execução da API utp/utapi028.p;
  • A execução da API é dependente do Microsoft Outlook, para o uso da mesma este programa deve estar instalado e o nome do(s) recipiente(s) devem estar no catálogo de endereços, ou então devem ser utilizados endereços de e-mail, e este catálogo deverá estar configurado no computador onde será feito o envio;
  • O organizador da reunião será o usuário padrão do Outlook da máquina que fará o envio.


Parâmetros de Entrada 


Temp-Table tt-reuniao: possui as definições da mensagem a ser enviada.


* ver Principais Validações da Temp-Table tt-configuracao

Atributo

Descrição

versao-integracao

Versão de Integração da API

modelo

Nome do modelo a ser utilizado para criação do arquivo

senha-modelo

Senha para desproteger o modelo a ser utilizado

exibir-construcao

Exibir construção do arquivo durante o processo

imprimir

Imprime o documento


Temp-Table tt-dados: possui as definições, gerais, sobre cada um dos campos a serem preenchidos no documento.

TEMP-TABLE tt-reuniao

Atributo

Tipo

Formato

Valor Inicial

i-versao-integracao

integer

">>9"


c-assunto

Char



c-corpo

Char



c-local

Char



c-categoria

Char



dt-dataini

Date

“99/99/9999”


dt-horaini

Char



l-lembrete

Logical


No

l-diatodo

Logical


No

i-duracao

Integer

“9999”


i-horaaviso

Integer



i-tipohorario

integer



c-convidadosreq

Char



c-convidadosopc

Char



c-convidadosrec

Char



i-importancia

Integer



i-tipo

Integer



l-periodico

Logical


No

i-tipoperiodo

Integer



i-intervalo

Integer



i-diassemana

Integer



i-mesdoano

Integer



i-diadomes

Integer



dt-fimperiodico

date



i-inicioocorrencia

integer



i-ocorrencias

integer



* ver Principais Validações da Temp-Table tt-reuniao


Atributo

Descrição

i-versao-integracao

Campo usado para verificar compatibilidade entre programa e api

c-assunto

Campo referente ao assunto do compromisso

c-corpo

Texto que seguira junto com o compromisso, é o corpo da mensagem

c-local

Local do compromisso

c-categoria

Categorias que o compromisso pertence separadas por “;”

dt-dataini

Data inicial do compromisso em formato mm/dd/yyyy

c-horaini

Hora de início do compromisso em formato hh:mm:ss

i-lembrete

Define se deve ser habilitado o lembrete para aviso prévio do compromisso

i-diatodo

Define se o compromisso ocupa todo o dia (hora de início deve ser informada)

i-duracao

Duração, em minutos, do compromisso.

i-horaaviso

Define o tempo, em minutos, para aviso prévio antes do compromisso (a função lembrete deverá estar ativada)

i-tipohorario

Define como deve ser mostrado o horário 0-Disponível 1-Provisório 2- Ocupado 3-Fora do escritório

c-convidadosreq

Convidados requeridos separados por “;”, podendo ser usado o nome do catálogo de endereços ou endereço de e-mail. *

c-convidadosopc

Convidados opcionais separados por “;”, podendo ser usado o nome do catálogo de endereços ou endereço de e-mail.*

c-convidadosrec

Convidados do tipo recurso separados por “;”, podendo ser usado o nome do catálogo de endereços ou endereço de e-mail. *

i-importancia

Importância da reunião 0-baixa 1-normal 2-alta

i-tipo

Tipo do compromisso 0-normal 1-pessoal 2-privado 3-confidencial.

i-periodico

Define se o compromisso é do tipo periódico, ou seja, se o mesmo tem várias ocorrências. **

i-tipoperiodo

Define o tipo de período a ser usado no compromisso.**

i-intervalo

Define o intervalo entre as ocorrências, como 2 meses 3 dias dependendo do tipo da mesma. **

i-diassemana

Máscara que define o(s) dias(s) de semana a serem usados para o compromisso. **

i-mesdoano

Define o mês de 1 a 12 para o compromisso. **

i-diadomes

Define o dia do mês para o compromisso. **

dt-fimperiodico

Data do fim das ocorrências de um compromisso periódico, sobrescreve o valor da variável i-ocorrências. **

i-inicioocorrencia

Define o dia de início de ocorrência para certos tipos de períodos como terceira (segunda) de cada mês. **

i-ocorrencias

Número de ocorrências de um compromisso periódico. **

*O contato deverá existir no catálogo de endereços

** Verificar tópico referente a compromissos periódicos em “Outras informações”.



Temp-Table tt-erros: possui todos os erros encontrados pela API.

TEMP-TABLE tt-erros

Atributo

Tipo

Formato

Valor Inicial

cod-erro

Integer



desc-erro

Character

x(256)


* ver Definição Temp-Table tt-erros

Atributo

Descrição

cod-erro

Número do erro

desc-erro

Descrição do erro ocorrido da ut-msgs


Execução

O programa utp/utapi028.p irá executar 2 validações básicas:




1º Validação:

Versão de Integração

O programa irá verificar se o programa chamador está íntegro com a API, e isto ocorre ao realizar a verificação da versão de integração passada como parâmetro. Caso a versão seja incompatível, a API finalizará a execução retornando o código de erro 3941.


2ª Validação:

Inconsistência ou Insuficiência dos Dados

O programa irá verificar a inconsistência e/ou insuficiência dos dados, e isto ocorre ao realizar a verificação dos dados passados como parâmetros. Caso os dados sejam inconsistentes ou insuficientes, a API finalizará a execução retornando o código de erro 8646.


O programa também executará outras validações referentes a erros específicos que serão abordados na seção “Possíveis erros” deste documento.

Cabe ao programa de origem, verificar a consistência do registro que está sendo enviado.

* ver descrições da Temp-Table tt-reuniao




Parâmetros de Saída

No retorno da execução do utp/utapi028.p, será retornado um dos valores via RETURN-VALUE:


NOK: 

Envio do compromisso interrompido, os dados passados como parâmetros, através das Temp-Tables, são inconsistentes ou foram insuficientes;

OK: 

Criação do compromisso com sucesso.


No caso do retorno ser NOK, todos os erros encontrados serão retornados através da Temp-Table tt-erros.




Outras Informações

Abaixo se encontram as principais validações a serem executadas em cada uma das Temp-Tables de entrada utilizadas pela API utp/utapi027.p.

Principais Validações da Temp-Table tt-configuracao:

  • Existência de dados na Temp-Table tt-configuracao;
  • Existência do modelo a ser utilizado, sendo passado como parâmetro pelo campo tt-configuracao.modelo;
  • Integridade dos dados.


Principais Validações da Temp-Table tt-dados :

  • Existência de dados na Temp-Table tt-dados;
  • Compatibilidade entre os valores dos campos e seus respectivos tipos de campos;
  • Integridade dos dados.


A seguir se encontram referências sobre os valores que alguns campos podem assumir:


Referência Tipo Campo

01 -  Check-Box

02 -  Drop-Down

03 -  Text-Input

04 - Imagem (pode ser apenas uma parte do propath ou deve ser o caminho completo)

05 - Arquivo (pode ser apenas uma parte do propath ou deve ser o caminho completo)




Exemplo

Abaixo programa exemplo de utilização da API.

Instruções:

  • Crie um formulário no Word com quatro campos texto, os campos precisam ter os nomes (nome, endereço, telefone, imagem, arquivo) e grave como um modelo do Word no diretório c:\tmp com o nome de a.dot.
  • O valor do campo imagem do exemplo abaixo deve ser substituído pelo caminho de uma imagem existente na máquina onde o programa será executado.
  • O valor do campo arquivo do exemplo abaixo deve ser substituído pelo caminho de um arquivo existente na máquina onde o programa será executado.
  • Execute o programa abaixo:
{utp/utapi027.i}                                                                

create tt-configuracao.       
assign tt-configuracao.versao-integracao = 1
           tt-configuracao.modelo  = "c:\tmp\a.dot"
           tt-configuracao.senha-modelo = ""
           tt-configuracao.exibir-construcao = no.
           tt-configuracao.imprimir = no.

create tt-dados.
assign tt-dados.campo-nome = "Nome"
           tt-dados.campo-tipo = 3
           tt-dados.campo-valor = "Datasul - Tecnologia".         

create tt-dados.
assign tt-dados.campo-nome = "Endereco"
           tt-dados.campo-tipo = 3
           tt-dados.campo-valor = "Santos Dummond, 831".         

create tt-dados.
assign tt-dados.campo-nome = "telefone"
           tt-dados.campo-tipo = 3
           tt-dados.campo-valor = "(47) 441-7000".         

create tt-dados.
assign tt-dados.campo-nome = "imagem"
           tt-dados.campo-tipo = 4
           tt-dados.campo-valor = "c:\tmp\amostra.jpg".
create tt-dados.
assign tt-dados.campo-nome = "arquivo"
           tt-dados.campo-tipo = 5
           tt-dados.campo-valor = "c:\tmp\arquivo.doc".

run utp/utapi027.p
                 (input-output table tt-configuracao,
                  input-output table tt-dados,
                  input-output table tt-erros).
/* Este código em comentário é um exemplo de como utilizar a API para salvar o documento gerado. 
/*Quando for utilizada essa codificação é necessário comentar a execução da API que se encontra acima.

DEFINE VARIABLE hApi AS HANDLE     NO-UNDO.

run utp/utapi027.p PERSISTENT SET hApi
                 (input-output table tt-configuracao,
                  input-output table tt-dados,
                  input-output table tt-erros).

RUN pi-salvar IN hApi (INPUT "c:\tmp\teste.doc").

RUN pi-finalizar IN hApi (INPUT TRUE).

RUN pi-getErrors IN hApi (OUTPUT TABLE tt-erros).

DELETE OBJECT hApi.
*/

if return-value = "nok" then do: 
    for each tt-erros: 
        disp tt-erros with 1 col width 500. 
    end.
end.
    


Técnicas de Importação/Importação

Técnica de exportação de dados:

 

Incluída na release 12.1.23, esta técnica visa facilitar as simulações dos problemas sem a necessidade de efetuar parametrizações de negócio (ou dados de negócio).

            Para gerar os dados necessários para a simulação é necessário que a API tenha a técnica implementada e esteja com o extrato de versão ativo. Seguindo isto, serão gerados no diretório temporário da sessão, alguns arquivos com extensão .json e nomeados de acordo com as temp-tables recebidas como parâmetro para gerar o relatório.

Estando com estes arquivos gerados (ex..: “tt-temp-table.json”), para simular o problema, basta efetuar a execução da API lendo estes registros e os passando como parâmetro.


Técnica de importação dos dados:

 

Simulação com os arquivos .Json oriundos da técnica acima. Abaixo um exemplo de código para a utapi027 efetuando um input desses registros:



{utp/utapi027.i}              


TEMP-TABLE tt-configuracao:READ-JSON("file", "C:\tmp\teste2\tt-configuracao.json", "empty").
TEMP-TABLE tt-dados:READ-JSON("file", "C:\tmp\teste2\tt-dados.json", "empty").
TEMP-TABLE tt-erros:READ-JSON("file", "C:\tmp\teste2\tt-erros.json", "empty").

/*
// Esta execucao somente preenche o formulario, sem salvar.
run utp/utapi027.p
                 (input-output table tt-configuracao,
                  input-output table tt-dados,
                  input-output table tt-erros).
                  */

//Este codigo em comentario a um exemplo de como utilizar a API para salvar o documento gerado. Quando 
//for utilizada essa codificacao e necessario comentar a execução da API que se encontra acima.

DEFINE VARIABLE hApi AS HANDLE     NO-UNDO.

run utp/utapi027.p PERSISTENT SET hApi
                 (input-output table tt-configuracao,
                  input-output table tt-dados,
                  input-output table tt-erros).

RUN pi-salvar IN hApi (INPUT "c:\tmp\teste.doc").
RUN pi-finalizar IN hApi (INPUT TRUE).
RUN pi-getErrors IN hApi (OUTPUT TABLE tt-erros).

DELETE OBJECT hApi.

if return-value = "NOK" then do: 
    for each tt-erros: 
        disp tt-erros with 1 col width 500. 
    end.
end.