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

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.

Árvore de páginas

Versões comparadas

Versão antiga 2

Nova versão 3

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

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