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 um email, uma mensagem de texto, um alerta no aplicativo ou uma notificação push, e pode opcionalmente permitir 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 instruções completas 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, é necessário configurar pelo menos um servidor de notificações para o método de entrega que você 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 que usam o Jitterbit Wrapper ou um wrapper personalizado, ou através do OneSignal, para aplicativos móveis nativos que usam 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: A 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, a URI e as seções de Security sejam preenchidas.
• Blabber, OneSignal e SMS requer que a seção de 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 que 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 necessário não estiver disponível, talvez seja necessário criar uma conexão de fonte de dados para App Builder (Sealed) da aplicação em que você 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 através de um objeto de dados público específico — um conjunto predefinido de colunas que determina detalhes como o destinatário, remetente e comportamento de entrega. O Método de Entrega selecionado ao criar uma notificação determina para 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:

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 recorrerá à URL padrão do site do servidor, configurada em IDE > Security Providers > More (no painel Configuration) > Sites. Para 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 para 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 Notifications novamente e selecione sua notificação no painel Notification Rules. Digite a mensagem no campo Body do painel Message; este campo é obrigatório e o evento de notificação falha com um erro se deixado em branco.

A mensagem suporta substituições usando a sintaxe {{fieldname}}, que o App Builder substitui pelo valor da 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 More > Edit HTML para editar o HTML subjacente da mensagem diretamente.

Para emails, um Subject também deve ser especificado, que também suporta 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 suporta múltiplos idiomas, você também pode traduzir uma notificação. Três campos suportam isso: o Body da notificação, seu Subject (para emails) e o Name de cada opção de resposta. Em vez de inserir texto literal nesses campos, insira 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 Translations.

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 Name 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. Defina Index para determinar a ordem da opção em relação às outras opções.
3. Defina Name para identificar a opção. Para uma opção SMS Reply, este também é o texto que o destinatário deve responder.
4. Defina 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 em 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 completar a resposta também depende da execução bem-sucedida desse evento. Consulte Data object event binding abaixo para as restrições que se aplicam a esse evento.

Data object event binding

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 própria página, se um estiver 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, no índice 10, contém os painéis Customer e CustomerAddress, e o segundo, no í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 apenas vincular 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 posterior ou resultado de validação do evento é perdido nesse ponto, pois o App Builder não exibe esses dados ao destinatário para eventos no nível da página. Você pode contornar isso exibindo dados nos painéis da página que mudam dependendo de o evento ter sido executado com sucesso. Pela mesma razão, um aviso de validação simplesmente impede a execução do evento, pois não há mecanismos para o destinatário aceitar ou rejeitar.

Neste ponto, você tem tudo o 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 completas

Os exemplos a seguir percorrem 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. Navegue até 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 precisa:

   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:

      Coluna	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. Navegue até 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, vincule à página Customers. Se a página que você deseja vincular não aparecer, certifique-se de que ela foi marcada como Public nas configurações de Edge Case.
      4. Clique em Save.

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

   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: CustomerRequestApprovalAlert.
   8. Clique em Save.
   9. Verifique se as Explicit Bindings estão corretas. Por exemplo: CustomerId - CustomerId.

6. Teste a notificação. Navegue até 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 popup com a mensagem de notificação.

Configuração de notificação 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. Navegue até 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. Navegue até IDE > User Management.
      1. No painel Users, localize o usuário que você deseja autenticar quando uma resposta SMS chegar. Clique duas vezes na linha do usuário ou clique no ícone no final dela. A caixa de diálogo User é aberta.

1. Clique em Mais > Chaves. A caixa de diálogo Chaves é aberta.
2. Clique em Criar. A caixa de diálogo Gerar Chave é aberta.
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 em 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. Ele 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. Reúna as credenciais do Twilio:

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

2. Conecte o App Builder ao Twilio, usando as credenciais reunidas 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 própria notificação SMS, seguindo o mesmo processo geral do exemplo anterior, mas desta vez, em vez de App Builder Alert, selecione Text Message como o Delivery Method:

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

      1. Navegue até App Workbench > Notifications.
      2. Clique em + Notification.
      3. Atribua um Name.
      4. Selecione Notification como o Purpose.

      5. Selecione Text Message como o 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) para o aplicativo em que está trabalhando.

      6. Clique em Create.

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

      1. Clique no botão +Table e adicione a tabela que a regra requer. Por exemplo: Customers.

      2. Clique na aba Columns e adicione as seguintes colunas:

         Coluna	Alias	Destino
         '+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 pode responder por SMS e outra que vincula a uma página:

5. Clique na aba Notificações.

6. Digite a seguinte mensagem no campo Corpo:

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

7. Clique no botão + Opção do painel Opções:

   1. Defina Índice como 10.
   2. Defina Nome como Análise.
   3. Selecione a página para vincular. No nosso exemplo, vincularemos à página Cliente do Northwinds. Se a página que deseja vincular não aparecer, certifique-se de que ela foi marcada como Pública nas configurações de Caso Extremo.
   4. Defina o Tipo de Opção como Link.
   5. Clique em Salvar.

8. Clique no botão + Opção do painel Opções:

   1. Defina Índice como 20.
   2. Defina Nome como 1.
   3. Selecione a página para vincular. No nosso exemplo, vincularemos à página Cliente do Northwinds e executaremos o evento Approve.
   4. Defina o Tipo de Opção como Resposta por SMS.
   5. Clique em Salvar.

9. Este exemplo pressupõe que a página Clientes já está marcada como Pública, 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 a seguir:

   1. Navegue até o evento do objeto de dados.
   2. Clique no ícone Lógica de Negócios.
   3. Clique no botão Eventos.
   4. Selecione o evento. Por exemplo: Request Approval.
   5. Clique em Registrar Existente no painel Ações.
   6. Selecione Notificação como o Tipo de Ação.
   7. Selecione a notificação que criamos na etapa anterior. Por exemplo: Customer_RequestApprovalSms.
   8. Clique em Salvar.
   9. Verifique se as Vinculações Explícitas estão corretas. 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 um evento de negócio ocorre, as notificações do sistema são mensagens de transmissão que um administrador envia manualmente ou agenda para enviar posteriormente a 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 atualizações de aplicações, que não precisam estar vinculadas a um registro específico ou acionadas por um evento.

As notificações do sistema são mostradas aos usuários ativos e permanecem em seu Centro de Notificações (no menu hambúrguer) até serem descartadas ou expiradas. As notificações do sistema fazem parte do recurso Manutenção e suportam apenas alertas no aplicativo. 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 > Manutenção, depois selecione a aba Notificações (disponível desde o App Builder 4.44) e siga estas etapas:

1. No painel Notificações Agendadas, clique no botão Agendar ou Enviar Agora.

2. Na caixa de diálogo Notificação, digite valores para os seguintes campos:

   • Para: Clique no campo e selecione um dos seguintes:

     • Todos

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

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

   • Agendar Para: (Opcional) Agende uma notificação para ser enviada posteriormente (por exemplo, uma hora antes de uma atualização de aplicação planejada).

   • Expira Em: 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ções.

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 guia Configurações.

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