Notificações no Jitterbit App Builder

Visão geral

Notificações são mensagens que o App Builder envia aos usuários da sua aplicação quando um evento ocorre, como um clique de botão ou uma verificação agendada. Uma notificação pode ser entregue como email, mensagem de texto, alerta no aplicativo ou notificação push, e opcionalmente permite que o destinatário responda navegando para uma página ou acionando um evento.

Esta página descreve as três etapas necessárias para configurar notificações em suas aplicações:

1. Configurar um servidor de notificações
   Configure o servidor usado para entregar notificações.

2. Criar uma notificação
   Defina o conteúdo da mensagem e o objeto usado para enviá-la.

3. Adicionar opções de resposta
   Opcionalmente, permita que os destinatários respondam navegando para uma página ou acionando um evento.

Esta página também inclui guias completos de todo o processo, com dois exemplos: uma notificação no aplicativo e uma mensagem SMS.

Para mensagens enviadas por administradores a vários usuários de uma vez, em vez de acionadas por um evento da aplicação, consulte Notificações do sistema.

Etapa 1: Configurar um servidor de notificações

Antes de enviar uma notificação, configure pelo menos um servidor de notificações para o método de entrega que planeja usar. O App Builder suporta os seguintes métodos de entrega:

• Email, enviado através de um servidor SMTP.

• SMS (mensagem de texto), enviado através do Twilio.

• No aplicativo (alerta do App Builder), um popup exibido ao destinatário enquanto ele está conectado ao aplicativo.

• Push, enviado através do Jitterbit Blabber, para aplicativos usando o Jitterbit Wrapper ou um wrapper customizado, ou através do OneSignal, para aplicativos móveis nativos usando sua própria conta OneSignal.

Para visualizar e gerenciar servidores de notificações, selecione IDE > Notification Servers:

A lista de servidores é composta pelas seguintes colunas:

• Name: O nome do servidor.

• Type: O tipo de notificação que pode ser configurada com esse servidor.

• Description: Uma breve descrição.

• URI: O URI (se aplicável).

• Status: O status atual do servidor.

Clique duas vezes em qualquer linha ou clique no ícone no final para visualizar e editar os detalhes de um determinado servidor. Todo servidor, exceto In-app, requer configuração antes do uso:

• SMTP (Email) requer que o endereço de origem, URI e seções de Security sejam preenchidos.
• Blabber, OneSignal e SMS requer que a seção Security seja preenchida.

Etapa 2: Criar uma notificação

Criar uma notificação significa criar uma regra de negócio com seu Purpose definido como Notification, a partir da aba Notifications do App Workbench. A regra define o conteúdo da mensagem da notificação e seleciona o objeto de dados público (Delivery Method) usado para enviá-la, como Email, Text Message, App Builder Alert ou Push Notification.

Para criar uma notificação:

1. Navegue até App Workbench > Notifications.
2. Clique em + Notification.
3. Atribua um Name.
4. Confirme se Purpose é Notification.
5. Selecione o Delivery Method que deseja usar. Cada método de entrega envia uma notificação através de um objeto de dados público específico, que determina os detalhes da notificação. Se o objeto de dados que precisa não estiver disponível, pode ser necessário criar uma conexão de fonte de dados para App Builder (Sealed) para o aplicativo em que está trabalhando.
6. Clique em Create.

Clicar em Create abre o Rule Builder no modo de edição, onde você define as colunas que a notificação usa, da mesma forma que faria ao editar qualquer outra regra de negócio. Para as colunas disponíveis para cada método de entrega, consulte Objetos de dados públicos por método de entrega abaixo.

Objetos de dados públicos por método de entrega

Cada método de entrega envia uma notificação por meio de um objeto de dados público específico — um conjunto predefinido de colunas que determina detalhes como destinatário, remetente e comportamento de entrega. O Método de Entrega selecionado ao criar uma notificação determina a qual objeto de dados público as colunas da notificação devem ser mapeadas, na definição mvSQL do Rule Builder.

As seções a seguir descrevem as colunas disponíveis para cada objeto de dados público, além das colunas comuns a todos eles.

Colunas comuns

Estas colunas são comuns a todos os objetos de dados públicos descritos abaixo:

Email

As colunas do objeto de dados público Email são as seguintes:

As notificações enviadas por email podem incluir anexos de muitos tipos de arquivo, como .pdf, .docx, .txt ou .xlsx, usando as colunas Attachment() e FileDataSourceId descritas abaixo. O App Builder anexa arquivos do diretório data/pdf por padrão ou do diretório especificado por FileDataSourceId.

Se a notificação contiver opções, a coluna AppBuilderUrl especifica a URL usada ao gerar links para essas opções. Se AppBuilderUrl não for fornecida, o App Builder recorre à URL padrão do site do servidor, configurada em IDE > Provedores de Segurança > Mais (do painel Configuração) > Sites. Para obter mais informações, consulte Sites e aliases.

Mensagem de Texto

O objeto de dados público Mensagem de Texto é usado para enviar mensagens SMS. As colunas do objeto de dados público Mensagem de Texto são as seguintes:

Alerta do App Builder

As colunas do objeto de dados público Alerta do App Builder são as seguintes. Este objeto é semelhante, mas não idêntico, ao objeto de dados público Notification_Create.

Notificação por Push

O objeto de dados público Notificação por Push envia uma notificação por push a um usuário. As colunas do objeto de dados público Notificação por Push são as seguintes:

Escrever a mensagem de notificação

Para escrever a mensagem da notificação, clique na aba Notificações novamente e selecione sua notificação no painel Regras de Notificação. Digite a mensagem no campo Body do painel Mensagem; esse campo é obrigatório e o evento de notificação falhará com um erro se for deixado em branco.

A mensagem oferece suporte a substituições usando a sintaxe {{fieldname}}, que o App Builder substitui pelo valor de coluna correspondente quando a notificação é enviada. Por exemplo, o corpo pode conter:

Hello {{CustomerName}},

Neste exemplo, CustomerName deve estar contido nas colunas da regra de notificação junto com os outros campos obrigatórios. As substituições podem adicionar um sinalizador url opcional para indicar que o valor é uma URL e requer codificação de URL, por exemplo {{fieldname|url}}. Um sinalizador HTML opcional trata a marcação HTML no valor como texto simples, por exemplo {{fieldname|HTML}} substitui um valor de <b>Jitterbit</b> como Jitterbit.

Para a maioria das mensagens, editar o campo Body em texto simples é suficiente. Se você precisar de formatação personalizada além de texto simples, clique em Mais > Editar HTML para editar o HTML subjacente da mensagem diretamente.

Para emails, também é necessário especificar um Subject, que também oferece suporte a substituições; como o campo Body, deixá-lo em branco causa falha do evento de notificação com um erro.

Traduções

Se sua aplicação oferece suporte a vários idiomas, você também pode traduzir uma notificação. Três campos oferecem suporte a isso: o Body da notificação, seu Subject (para emails) e o Name de cada opção de resposta. Em vez de digitar texto literal nesses campos, digite uma chave de tradução; o App Builder procura o valor para o idioma do destinatário no pacote de tradução da aplicação quando a notificação é enviada.

Você deve adicionar manualmente essas chaves de tradução ao pacote de tradução do aplicativo; o App Builder não as importa automaticamente.

Se editar a mensagem usando More > Edit HTML, adicione a chave de tradução como uma string simples em vez de HTML, ou a busca falhará.

Para mais informações sobre como configurar idiomas e pacotes de tradução, consulte Traduções.

Etapa 3: Adicionar opções de resposta

Uma notificação pode incluir opcionalmente uma ou mais opções de resposta que permitem ao destinatário responder. Uma notificação sem opções é puramente informativa: o App Builder não rastreia uma resposta e nenhum link é adicionado à mensagem.

Quando uma notificação tem uma ou mais opções, o App Builder rastreia a resposta do destinatário automaticamente. Para emails e alertas do App Builder, cada opção é um link clicável de volta para o App Builder. Para SMS, o destinatário responde com o Nome da opção para selecioná-la.

Os links de notificação expiram após 7 dias e não podem ser configurados para durar mais tempo.

Para adicionar uma opção de resposta a uma notificação:

1. No painel Options da notificação, clique no botão + Option.
2. Configure Index para determinar a ordem da opção em relação às outras opções.
3. Configure Name para identificar a opção. Para uma opção SMS Reply, este é também o texto com o qual o destinatário deve responder.
4. Configure Option Type como Link ou SMS Reply.
5. Para uma opção Link, selecione a página para vincular em Link To Page. A página deve estar marcada como Public nas suas configurações de Edge Case.
6. Clique em Save.

Navegar até a página selecionada em Link To Page conclui a resposta para uma opção Link. Se essa página também tiver um evento de lógica de negócios vinculado a ela, o evento é executado antes da página ser renderizada, e concluir a resposta depende também da execução bem-sucedida desse evento. Consulte Vinculação de evento de objeto de dados abaixo para as restrições que se aplicam a esse evento.

Vinculação de evento de objeto de dados

Quando a página vinculada no campo Link To Page de uma opção de resposta também tem um evento de lógica de negócios vinculado a ela, esse evento deve pertencer ao primeiro painel da página (o painel com o índice mais baixo, na posição superior esquerda) ou ao objeto de dados público da página, se um for definido. Eventos que pertencem a qualquer outro painel na página não podem ser vinculados a uma opção de resposta.

Por exemplo, considere uma página empilhada com dois grupos lado a lado: o primeiro, com índice 10, contém os painéis Customer e CustomerAddress, e o segundo, com índice 20, contém os painéis Employee e EmployeeAddress:

Customer é o primeiro painel da página, portanto seus eventos são elegíveis. CustomerAddress, Employee e EmployeeAddress não são elegíveis, pois nenhum deles é o primeiro painel da página.

O App Builder também permite vinculação apenas a eventos personalizados, não a eventos do sistema. Por exemplo, você não pode vincular aos eventos Save, Insert, Update ou Delete.

Quando o evento vinculado é concluído, o App Builder redireciona o destinatário para a página, mas qualquer mensagem pós ou resultado de validação do evento é perdido nesse ponto, já que o App Builder não exibe esses itens ao destinatário para eventos em nível de página. Você pode contornar isso exibindo dados nos painéis da página que mudam com base no fato de o evento ter sido executado com sucesso. Pela mesma razão, um aviso de validação simplesmente impede que o evento seja executado, pois não há mecanismos para o destinatário aceitar ou rejeitar.

Neste ponto, você tem tudo que precisa para criar uma notificação: um servidor para entregá-la, uma regra que define sua mensagem e dados, e, opcionalmente, uma ou mais opções de resposta.

Instruções passo a passo completas

Os exemplos a seguir demonstram todo o processo de criação de uma notificação, desde a configuração de um método de entrega até a adição de uma opção de resposta. O primeiro exemplo usa App Builder Alert como método de entrega; o segundo usa Text Message (SMS).

Configuração de notificação de exemplo

Este exemplo adiciona uma notificação de aprovação de cliente à página Clientes de um aplicativo hipotético chamado Northwinds, usando App Builder Alert como método de entrega.

1. Crie a notificação e defina seu método de entrega:

   1. Acesse App Workbench.
   2. Clique em Notifications.
   3. Clique em + Notification.
   4. Atribua um Name. Por exemplo: CustomersRequestApprovalAlert.
   5. Confirme que Purpose é Notification.

   6. Selecione App Builder Alert como Delivery Method.

      Nota

      Se você não vir este objeto de dados disponível, crie uma conexão de fonte de dados para App Builder (Sealed) do aplicativo em que está trabalhando.

   7. Clique em Create.

2. Defina o mvSQL da notificação, mapeando a tabela Customers para as colunas que o objeto App Builder Alert necessita:

   1. Clique no botão +Tables.
   2. Adicione sua tabela Select From, que neste caso é Customers.

   3. Adicione as seguintes colunas e clique na aba Columns para definir:

      Column	Alias	Target
      'all'	To	To
      "C".CustomerId	CustomerId	Binding()
      "C".CustomerName	CustomerName

      Nota

      CustomerName é adicionado aqui para que possa ser usado posteriormente como parâmetro de substituição na mensagem de notificação.

3. Escreva a mensagem da notificação:

   1. Acesse App Workbench.
   2. Clique em Notifications.
   3. Selecione a notificação que você criou na etapa 1, que em nosso exemplo é CustomerRequestApprovalAlert.

   4. Digite a mensagem no campo Body, por exemplo:

      Please review the following customer:
      Customer: {{CustomerName}}

   5. Clique no ícone e digite qualquer Technical Help para ajudar a explicar a notificação a outros desenvolvedores.

4. (Opcional) Adicione uma opção de resposta que vincula a uma página:

   1. Na página App Workbench > Notifications, selecione a notificação.
   2. Clique no botão + Option.
   3. Crie uma nova opção:
      1. Defina Index como 10.
      2. Defina Name como Review.
      3. Selecione o valor Link To Page. Neste exemplo, crie um vínculo para a página Customers. Se a página que deseja vincular não aparecer, verifique se ela foi marcada como Public em suas configurações de Edge Case.
      4. Clique em Save.

5. Este exemplo assume que a página Customers já está marcada como Public, com um evento denominado Request Approval definido em seu primeiro painel. Vincule esse evento ao link da opção para que seja executado quando o destinatário a seguir:

   1. Acesse o evento do objeto de dados.
   2. Clique no ícone Business Logic.
   3. Clique no botão Events.
   4. Selecione o evento. Por exemplo: Request Approval.
   5. Clique em Register Existing no painel Actions.
   6. Selecione Notification como Action Type.
   7. Selecione a notificação que criamos na etapa anterior. Por exemplo: CustomerRequestApprovalAlert.
   8. Clique em Save.
   9. Verifique se os Explicit Bindings estão corretos. Por exemplo: CustomerId - CustomerId.

6. Teste a notificação. Acesse sua página e clique no botão que executa o evento de notificação. Todos os usuários do App Builder conectados devem ver um pop-up com a mensagem de notificação.

Configuração de notificação por SMS de exemplo

Este exemplo adiciona a mesma notificação de aprovação de cliente à mesma página Customers, usando Text Message (SMS) como método de entrega.

1. Configure a segurança do App Builder para que o App Builder possa autenticar respostas SMS recebidas do Twilio:

   1. Acesse IDE > Security Providers.
   2. Clique em + User Authentication no painel User Authentication.
      1. Digite um Name (por exemplo, Http Basic Auth).
      2. Selecione HTTP Basic Authentication como Type.
      3. Clique em Enabled para ativar.
      4. Clique em Save.
   3. Acesse IDE > User Management.
      1. No painel Users, localize o usuário que deseja autenticar quando uma resposta SMS chegar. Clique duas vezes na linha do usuário ou clique no ícone ao final dela. A caixa de diálogo User abre.

1. Clique em Mais > Chaves. A caixa de diálogo Chaves abre.
2. Clique em Criar. A caixa de diálogo Gerar Chave abre.
3. Selecione o provedor Http Basic Auth criado anteriormente.
4. Clique em Salvar.

1. Configure o Twilio para enviar e receber mensagens SMS:

   1. Crie um serviço de mensagens:

      1. Faça login na sua conta do Twilio.
      2. Navegue até Communications Cloud > Programmable SMS.
      3. Clique em Messaging Services.
      4. Crie um novo Messaging Service (Notificações, bidirecional) e anexe um número de telefone do Twilio a ele.
      5. Anote o MessagingServiceSid. Isso será usado para configuração posteriormente.
      6. Ative a opção Process Inbound Message.
      7. Digite a seguinte URL de solicitação, substituindo <username>, <secret_key> e <your_AppBuilder_Server> pelos seus valores: https://<username>:<secret_key>@<your_AppBuilder_Server>/webhook/v1/vinyl/bridge_inbound

   2. Colete as credenciais do Twilio:

      1. Navegue até Console Dashboard > Settings.
      2. Anote as seguintes credenciais ao vivo:
         • Account Sid
         • Auth Token

2. Conecte o App Builder ao Twilio, usando as credenciais coletadas na etapa anterior:

   1. Navegue até IDE > Servidores de Notificação.
   2. Clique duas vezes na linha SMS.
   3. Adicione a seguinte configuração:
      • Nome de Usuário: Digite seu Account Sid do Twilio.
      • Senha: Digite seu Auth Token do Twilio.
      • MessagingServiceSid: Digite seu MessagingServiceSid do Twilio.

3. Defina a URL do site que o App Builder usa ao gerar links na mensagem SMS:

   1. Navegue até IDE > Provedores de Segurança.
   2. Em Configuração, clique em Mais > Sites.
   3. Clique em + Site.
   4. Defina o valor da URL para a URL do seu site. Por exemplo: https://vinyl.jitterbit.com.
   5. Clique em Salvar.

4. Agora, crie e configure a notificação de SMS em si, seguindo o mesmo processo geral do exemplo anterior, mas desta vez, em vez de App Builder Alert, selecione Mensagem de Texto como o Método de Entrega:

   1. Crie a notificação e defina seu método de entrega:

      1. Navegue até App Workbench > Notificações.
      2. Clique em + Notificação.
      3. Atribua um Nome.
      4. Selecione Notificação como a Finalidade.

      5. Selecione Mensagem de Texto como o Método de Entrega.

         Nota

         Se você não vir este objeto de dados disponível, crie uma conexão de fonte de dados para App Builder (Sealed) para o aplicativo em que está trabalhando.

      6. Clique em Criar.

   2. Defina o mvSQL da notificação, mapeando o número de telefone e as colunas do cliente para o objeto Mensagem de Texto:

      1. Clique no botão +Tabela e adicione a tabela que a regra exige. Por ex.: Customers.

      2. Clique na guia Colunas e adicione as seguintes colunas:

         Coluna	Alias	Alvo
         '+15551112222' (substitua pelo seu número de telefone)	To()	To()
         "C".CustomerId	CustomerId	Binding()
         "C".CustomerName	CustomerName

         Nota

         CustomerName é adicionado aqui para que possa ser usado posteriormente como um parâmetro de substituição na mensagem de notificação.

   3. Escreva a mensagem e adicione duas opções de resposta: uma que o destinatário possa responder por SMS e outra que vincula a uma página:

5. Clique na aba Notificações.

6. Digite a seguinte mensagem no campo Body:

   Reply {{1}} to approve {{CustomerName}}. Review {{Review}}
   

7. Clique no botão + Option no painel Options:

   1. Defina Index como 10.
   2. Defina Name como Review.
   3. Selecione a página para vincular. No nosso exemplo, vamos vincular à página Customer do Northwinds. Se a página que você quer vincular não aparecer, verifique se ela foi marcada como Public nas configurações de Edge Case.
   4. Defina Option Type como Link.
   5. Clique em Save.

8. Clique no botão + Option no painel Options:

   1. Defina Index como 20.
   2. Defina Name como 1.
   3. Selecione a página para vincular. No nosso exemplo, vamos vincular à página Customer do Northwinds e executar o evento Approve.
   4. Defina Option Type como SMS Reply.
   5. Clique em Save.

9. Este exemplo assume que a página Customers já está marcada como Public, com um evento chamado Request Approval definido em seu primeiro painel. Vincule esse evento à opção Link para que seja executado quando o destinatário clicar nele:

   1. Navegue até o evento do objeto de dados.
   2. Clique no ícone Business Logic.
   3. Clique no botão Events.
   4. Selecione o evento. Por exemplo: Request Approval.
   5. Clique em Register Existing no painel Actions.
   6. Selecione Notification como Action Type.
   7. Selecione a notificação que criamos na etapa anterior. Por exemplo: Customer_RequestApprovalSms.
   8. Clique em Save.
   9. Verifique se os Explicit Bindings estão corretos. Por exemplo: CustomerId - CustomerId.

10. Teste a notificação. Navegue até sua página e clique no botão que executa o evento de notificação.

Notificações do sistema

Diferentemente das notificações descritas anteriormente nesta página, que o App Builder envia automaticamente para um destinatário específico quando ocorre um evento de negócios, as notificações do sistema são mensagens de broadcast que um administrador envia manualmente ou agenda para enviar posteriormente para um grupo de usuários de uma vez, por exemplo, todos com acesso a uma aplicação ou um grupo de segurança ou função específica. Os administradores usam notificações do sistema para coisas como janelas de manutenção planejadas ou upgrades de aplicação, que não precisam estar vinculadas a um registro específico ou ser acionadas por um evento.

As notificações do sistema são mostradas aos usuários ativos e permanecem em seu Notification Center (no menu hambúrguer) até serem descartadas ou expiradas. As notificações do sistema fazem parte do recurso Maintenance e suportam apenas alertas no app. Elas também são específicas do ambiente: diferentemente das notificações de aplicação, que são promovidas com seu código entre ambientes, uma notificação do sistema deve ser recriada em cada ambiente.

Para configurar uma notificação do sistema, selecione IDE > Maintenance e depois selecione a aba Notifications (disponível desde o App Builder 4.44) e siga estas etapas:

1. No painel Scheduled Notifications, clique no botão Schedule or Send Now.

2. Na caixa de diálogo Notification, digite os valores para os seguintes campos:

   • To: Clique no campo e depois selecione um dos seguintes:

     • All

     • Um grupo de usuários com base no seguinte:

       • Seu acesso a uma aplicação ou fonte de dados concedido por seus grupos ou funções.

       • Grupos de segurança.

       • As funções da fonte de dados.

   • From: Define quem enviou a notificação (normalmente o usuário de serviço).

   • Schedule For: (Opcional) Agenda uma notificação para ser enviada depois (por exemplo, uma hora antes de um upgrade de aplicação planejado).

   • Expires On: Uma data/hora quando a notificação expira e não será mais mostrada aos usuários. Neste momento, os usuários que viram e descartaram a mensagem têm a notificação removida de seus centros de notificação.

3. Body: O conteúdo da mensagem exibida aos usuários.

4. Clique no botão Enviar ou Agendar.

Um serviço em segundo plano envia notificações agendadas. Por padrão, o serviço é executado pela conta do Usuário de Serviço. Para alterar qual usuário executa o serviço, siga estas etapas:

1. Selecione IDE > Manutenção, depois selecione a aba Configurações.

2. Clique no menu Usuário de Notificação em Segundo Plano e selecione o usuário para executar o serviço.