Histórico da Página

Button

Texto	Voltar
Link	https://tdn.totvs.com/pages/releaseview.action?pageId=857586913

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 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.

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

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:

Expandir

title	Clique aqui para visualizar...

Bloco de código

language	ruby

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

Bloco de código

language	ruby

{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

Compromissos periódicos:

Os compromissos periódicos podem ser dos seguintes tipos:

Diário (0):

Os compromissos do tipo diário são executados em todas as semanas do ano, podendo ser de n em n dias conforme definição do usuário para a variável i-intervalo.
Exemplo da definição de um compromisso diário:
Bloco de código
language ruby
assign i-tipoperiodo = 0 /*define o tipo do período como diário */ i-intervalo = 2. /* define o intervalo entre as ocorrências */
Desta forma será agendado um compromisso do tipo diário que acontece de 2 em 2 dias.

Semanal (1):

Os compromissos do tipo semanal são executados de n em n semanas conforme a variável i-intervalo em determinados dias da semana conforme a variável i-diassemana.
Exemplo da definição de um compromisso semanal:
Bloco de código
language ruby
assign i-tipoperiodo = 1 /* define o tipo do período como semanal */ i-intervalo = 2 i-diassemana = 3.
Desta forma será agendado um compromisso do tipo semanal que acontece de 2 em 2 semanas no domingo e na segunda.

Mensal (2):

Os compromissos do tipo mensal são executados de n em n meses conforme a variável i-intervalo no dia x conforme a variável i-diadomes.

Exemplo da definição de um compromisso mensal:

Bloco de código

language	ruby

 assign i-tipoperiodo = 2 /* define o tipo do período como mensal */
        i-intervalo   = 5
        i-diadomes    = 14.

Desta forma será agendado um compromisso do tipo mensal que acontece de 5 em 5 meses no dia 14.

Mensal com início de ocorrência (3):

Os compromissos do tipo mensal com início de ocorrência são executados de n em n meses conforme a variável i-intervalo no primeiro, segundo, terceiro, quarto ou ultimo dia da ocorrência do dia definido na variável i-diassemana conforme a variável i-inicioocorrencia.

Exemplo da definição de um compromisso mensal com início de ocorrência:

Bloco de código

language	ruby

assign i-tipoperiodo = 3 /* define o tipo do período como mensal com início de ocorrência */
       i-intervalo   = 4
       i-diassemana  = 1
       i-inicioocorrencia = 2.

Desta forma será agendado um compromisso do tipo mensal com início de ocorrência que acontece de 4 em 4 meses no segundo domingo do mês.

No caso particular de compromissos com início de ocorrência, deve se levar em consideração que a variável i-diassemana deverá conter o valor de apenas um dia da semana ou então o valor 127 para o primeiro dia, o valor 65 para o primeiro dia de fim de semana ou 62 para o primeiro dia útil. Note que 127 é a soma de todos os dias da semana, 65 é a soma de sábado e domingo e 62 e a soma de segunda a sexta, estes são os únicos valores somados permitidos para esse tipo de ocorrência exclusivamente.

Anual (5):

Os compromissos do tipo anual ocorrem 1 vez por ano no mês n definido pela variável i-mesdoano no dia n definido pela variável i-diadomes.
Exemplo da definição de um compromisso anual:
Bloco de código
language ruby
assign i-tipoperiodo = 5 /* define o tipo do período como anual */ i-diadomes = 30 i-mesdoano = 4. /* define o mês do ano */
Desta forma será agendado um compromisso do tipo anual que acontece uma vez pôr ano no dia 30 do mês 4.

Anual com início de ocorrência (6):

Os compromissos do tipo anual com início de ocorrência ocorrem 1 vez por ano no mês n conforme a variável i-mesdoano, no primeiro, segundo, terceiro, quarto ou ultimo dia da ocorrência do dia definido na variável i-diassemana conforme a variável i-inicioocorrencia.
Exemplo da definição de um compromisso anual com início de ocorrência:
Bloco de código
language ruby
assign i-tipoperiodo = 6 /* define o tipo do período como anual */ i-mesdoano = 5 i-diassemana = 16 i-inicioocorrencia = 2.
Desta forma será agendado um compromisso do tipo anual com início de ocorrência que acontece no mês 5 na segunda quinta-feira. Os valores da variável i-diassemana são os mesmos do tipo de período 3.

Variável i-diassemana:

A variável i-diassemana é usada em vários tipos de compromisso, e ela consiste na soma dos valores para definir os dias:

1 -Domingo

2 -Segunda-feira

4 -Terça-feira

8 -Quarta-feira

16-Quinta-feira

32-Sexta-feira

64-Sabado

Exemplos:

Bloco de código

language	ruby

assign diassemana = 3    /* 1+2 domingo + segunda  */
assign diassemana = 127  /* todos os dias */

Definições das Temp-Tables a serem utilizadas pela API utp/utapi028.p

Definição Temp-Table tt-reuniao:

Bloco de código

language	ruby

DEFINE TEMP-TABLE tt-reuniao
    field i-versao-integracao AS INTEGER FORMAT ">>9" 
    field c-assunto           AS CHAR
    FIELD c-corpo             AS CHAR
    FIELD c-local             AS CHAR
    FIELD c-categoria         AS CHAR
    FIELD dt-dataini          AS DATE FORMAT "99/99/9999"
    FIELD c-horaini           AS CHAR
    FIELD l-lembrete          AS LOGICAL INIT NO
    FIELD l-diatodo           AS LOGICAL INIT NO
    FIELD i-duracao           AS INTEGER FORMAT "9999"
    FIELD i-horaaviso         AS INTEGER
    FIELD i-tipohorario       AS INTEGER
    FIELD c-convidadosreq     AS CHAR
    FIELD c-convidadosopc     AS CHAR
    FIELD c-convidadosrec     AS CHAR
    FIELD i-importancia       AS INTEGER
    FIELD i-tipo              AS INTEGER
    FIELD l-periodico         AS LOGICAL INIT NO
    FIELD i-tipoperiodo       AS INTEGER
    FIELD i-intervalo         AS INTEGER
    FIELD i-diassemana        AS INTEGER
    FIELD i-mesdoano          AS INTEGER
    FIELD i-diadomes          AS INTEGER
    FIELD dt-fimperiodico     AS DATE
    FIELD i-inicioocorrencia  AS INTEGER
    FIELD i-ocorrencias       AS INTEGER.

Exemplo de Utilização

Bloco de código

language	ruby

{utp/utapi028.i}
CREATE tt-reuniao.
ASSIGN c-assunto = "Assunto da mensagem"
       c-corpo = " Aqui vai um grande texto para o corpo da mensagem"
       c-local = " Local qualquer"
       dt-dataini = 12/23/2002
       l-lembrete = FALSE
       c-horaini = "00:00:00"
       l-diatodo = FALSE
       i-duracao = 800
       i-horaaviso = 50
       i-importancia = 0 
       i-tipohorario = 3 
       c-convidadosreq = "[email protected]"
       c-convidadosopc = "João da Silva"
       c-convidadosrec = "Luiz Cesar Medeiros Filho;Joao da Silva"
       i-tipo =2
       c-categoria = "Importante"
/* inicia periódico */
       l-periodico = TRUE
       i-tipoperiodo = 1
       i-diassemana = 127
       i-inicioocorrencia = 2
       i-intervalo = 2.

run utp/utapi028.p persistent set h-utapi028.
run pi-execute in h-utapi028 (input table tt-reuniao,output table tt-erros).
for each tt-erros:
        disp "Erro: " tt-erros.cod-erro skip
             "Descrição: " tt-erros.desc-erro format "x(50)".
end.

delete procedure h-utapi028.

Possíveis erros

Erro 4786: Hora informada não está correta!

Erro ocasionado quando o campo c-horaini não é preenchido corretamente, ou seja não contém uma hora no formato HH:MM:SS, ou seu tamanho não tem 8 caracteres, ou a hora informada é maior que 23, os minutos informados maiores que 59 ou os segundos informados também maiores que 59.
Deve ser também levado em consideração que uma hora do tipo 2:29:35 está errada pois seu formato é H:MM:SS e não corresponde ao formato solicitado pela api. O correto seria 02:29:35.

Erro 26816: Um ou mais convidados estão incorretos

Erro causado pelo fato de um dos convidados da reunião não existir no catálogo de endereço global, ou seja, do servidor.
Neste caso deve ser verificado se os campos c-convidadosreq, c-convidadosopc e
c-convidadosrec foram preenchidos com nomes válidos no catálogo de endereços global e/ou endereços de e-mail separados por “;”.

(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.

Árvore de páginas

Versões comparadas

Versão antiga 1

Nova versão 2

Chave

API de Envio de compromisso via Outlook (001)

Considerações Gerais

Parâmetros de Entrada

Execução

Parâmetros de Saída

Outras Informações

Exemplo

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

Definições das Temp-Tables a serem utilizadas pela API utp/utapi028.p

Exemplo de Utilização

Possíveis erros

Erro 4786: Hora informada não está correta!

Erro 26816: Um ou mais convidados estão incorretos