Adobe Acrobat Sign para Salesforce - Guia do desenvolvedor

O Adobe Acrobat Sign for Salesforce: Guia do desenvolvedor foi pensado para ajudar desenvolvedores do Salesforce a saber mais sobre os objetos e parâmetros necessários para integrar o pacote da Salesforce com o Adobe Acrobat Sign.

Consulte os tópicos deste documento para saber mais sobre:

• Diretrizes para desenvolvedores
• Atualizar ordem
• Serviços Apex
• Serviços de API
• Serviços em lote do Apex
• Lote de modelos de contrato
• Lote de serviço de modelo de contrato
• Serviços REST
• Serviços de fundo
• Alterações na compatibilidade com versões anteriores

• Se precisar saber quando o contrato está totalmente assinado, implemente um acionador Apex no objeto echosign_dev1__SIGN_Agreement__c após ou antes da atualização (dependendo do caso de uso e dos requisitos). Quando o campo echosign_dev1__Status__c é alterado para Assinado ou Aprovado ou outros status finais, o contrato é concluído.
• Se você precisar saber quando cada PDF assinado individual é inserido, se por exemplo precisar obter cada PDF assinado intermediário, implemente um acionador Apex nos objetos Attachment ou ContentVersion, após a inserção, e observe um contrato principal e um nome que termine em "- signed.pdf" ou "- approved.pdf" ou outro status final
• Se precisar saber quando um recipient individual assinou ou aprovou, implemente um acionador Apex no objeto echosign_dev1__SIGN_Recipients__c, após ou antes da atualização (dependendo do caso de uso e dos requisitos). Quando o campo echosign_dev1__Status__c é alterado para Assinado ou Aprovado ou outros status finais, o recipient foi concluído.
• Se você precisar saber quando ocorre um evento específico que faz parte do processo de assinatura, como o envio de um contrato para assinatura ou um envio de lembrete, um acionador pode ser criado no objeto de eventos do contrato (echosign_dev1__SIGN_AgreementEvent__c) para verificar o tipo do evento
• Os nomes dos status finais de um contrato concluído são: "Assinado", "Aprovado", "Aceito", "Preenchido com formulário" e "Entregue"
  
• Os nomes do Status final do contrato para um contrato encerrado são: "Cancelado/Recusado" e "Expirado"

Ordem de atualizações

Na v21, a ordem das atualizações foi alterada. Veja abaixo a nova sequência em que o contrato e seus objetos relacionados são atualizados:

1. Anexos 
2. Destinatários 
3. Contrato (status e outros atributos)
4. Eventos do contrato 
5. Feeds do Chatter 

Serviços Apex

Método Apex em uso

A partir do Acrobat Sign for Salesforce V 21.0, todos os processos assíncronos (incluindo atualizações automáticas e mapeamentos de dados) usam o método Em fila em vez do método Futuro, conforme recomendado pela Salesforce.
Com essa alteração, todos os trabalhos de personalização que você adicionou à fila do Salesforce para atualização automática ou processo de mapeamento de dados apresentarão falha com este erro: “System.LimitException: muitas tarefas em fila adicionadas à fila:2.”

A falha acontece porque um processo enfileirado só pode adicionar uma tarefa filho enfileirada, que já está ocupada pelo Acrobat Sign. Para obter detalhes, consulte Limites de Apex em fila.

Quando o status do contrato não é alterado ou o mapeamento de dados não é executado corretamente, ele pode exibir este erro: “Ao encadear trabalhos, você pode adicionar apenas um trabalho de um trabalho em execução com System.enqueueJob, o que significa que apenas um trabalho secundário pode existir para cada trabalho principal na fila. Não se permite iniciar vários trabalhos secundários a partir do mesmo trabalho em fila.”

Para solucionar esse erro, localize o acionador, construtor de processo ou fluxo de trabalho com problema e desative-o, alterne-o para usar uma chamada assíncrona ou agende-o para depois.

Serviço de modelo de contrato

O serviço de modelo de contrato é exposto como um serviço global do Apex pelo pacote gerenciado. Isso permite que o código do Apex fora do pacote gerenciado carregue contratos com base em modelos de contrato existentes. A classe e todos os métodos expostos são marcados como global para permitir esse acesso.

O serviço Apex é exposto por meio desta classe de invocação: echosign_dev1.AgreementTemplateService

Métodos

 Construtores

Propriedades da classe global

Variáveis de tempo de execução

A classe global echosign_dev1.AgreementTemplateVariable tem os dois campos globais a seguir:

• nome: o nome da variável, que deve corresponder a um nome de variável de tempo de execução configurado no modelo de contrato.
• valor: o valor da variável usada durante o carregamento do modelo. O valor depende de onde a variável foi usada. Por exemplo, para um destinatário, deve ser uma ID de contato, lead ou registro de usuário ou um email. Para uma variável de documento, deve ser uma ID de registro de anexo.

Resultado

Cada método retorna a ID do registro do contrato recém-criado ou lança uma exceção com uma mensagem de erro detalhada se algo der errado durante a operação de carregamento.

Serviços de API

O serviço de modelo de API para assinar eletronicamente da Adobe é exposto como um serviço global do Apex pelo pacote gerenciado. Isso permite que o código do Apex fora do pacote gerenciado chame um conjunto de APIs para assinar eletronicamente da Adobe por meio desses empacotadores. Os empacotadores simplificam muito a chamada de API porque os consumidores não precisam criar modelos de dados de solicitação e resposta. Além disso, os clientes não precisam lidar com a transformação dos dados do Salesforce em modelos de dados para assinar eletronicamente. A maior parte da complexidade é abstraída do consumidor. Por exemplo, para enviar um contrato que o consumidor acaba de transmitir na ID de registro do contrato, o serviço tratará de consultá-lo, extrair todos os dados relevantes, transmiti-lo na API e analisar o resultado.

A classe e todos os métodos expostos são marcados como global para permitir esse acesso.

• v17 e anteriores chamam APIs SOAP
• v18 e posterior chamam APIs REST

O serviço Apex é exposto por meio da seguinte classe de chamada: echosign_dev1.EchoSignApiService

Aprimoramento da API do Apex para destinatários alternativos

A partir da versão 24.14 ou posterior, a API do Apex atualizada permite substituir ou adicionar destinatários alternativos e está acessível na classe global “EchoSignApiService”. Dois novos elementos foram introduzidos:

• Uma função global:
  

  /**

  * Parâmetros de entrada:

  * toBeChangedRecipientId: SIGN_Recipient__c Id

  * newRecipientStr: string JSON de SIGN_Recipient__c de um novo destinatário para substituição de destinatário ou alternativo

  * changeType: REPLACE ou ALTERNATE

  */

  global static void changeRecipient(Id toBeChangedRecipientId, String newRecipientStr, RECIPIENT_CHANGE_TYPE changeType )

• Uma enumeração global: RECIPIENT_CHANGE_TYPE {REPLACE, ALTERNATE}

Código de exemplo para chamar esta API para destinatários (tipo de destinatário como Email)

// primeiro consulte todos os destinatários associados ao contrato

List<SIGN_Recipients__c> recipients = [SELECT Id, echosign_dev1__Agreement__c, echosign_dev1__Email_Address__c, echosign_dev1__ParticipantSet__c, echosign_dev1__Recipient_Type__c, echosign_dev1__Order_Number__c FROM echosign_dev1__SIGN_Recipients__c where echosign_dev1__Agreement__c = 'a0P7X000008Cc1GUAS'];

SIGN_Recipients__c newRecipient = null;

SIGN_Recipients__c replacedRecipient = null;

// localize o destinatário que precisa ser substituído ou um alternativo

// nesse caso, localize o destinatário por seu email.

// Você pode adicionar mais condições para localizar o destinatário que deve ser substituído ou que precisa de uma alternativa.

for(SIGN_Recipients__c recipient: recipients) {

    if (rep.echosign_dev1__Email_Address__c == 'someUser@example.com') {

         newRecipient = recipient.clone(false, true, false, false);

         replacedRecipient = recipient;

    }

}

// atualizar endereço de email para novo destinatário

newRecipient.echosign_dev1__Email_Address__c = ''someNewUser@abc.com';

// serializar para string json

String newRecipientStr = JSON.serialize(newRecipient);

Experimente o {

    echosign_dev1.EchoSignApiService.changeRecipient(replacedRecipient.Id, newRecipientStr, EchoSignApiService.RECIPIENT_CHANGE_TYPE.REPLACE);

} catch (Exception ex) {

    // tratar a exceção e relançar se necessário

}

Métodos

Classes internas

• Classe global: DocumentHistoryEvent

• Classe global: DocumentInfo
  

• Classe global: ParticipantInfo

• Classe global: SendDocumentResult

• Classe global: SigningUrl
  

Serviços em lote do Apex

Expõe as principais ações de contratos para assinar eletronicamente em massa, permitindo que uma operação seja executada em um conjunto de contratos. Esta classe implementa a interface Database.Batchable do Salesforce. Ela pode processar qualquer número de registros, que serão divididos em conjuntos de 5, e processar cada conjunto como uma transação individual, o que permite que os limites do regulador sejam respeitados.

O serviço em lote do Apex é exposto por meio da seguinte classe de chamada: echosign_dev1.EchoSignActionBatch

Parâmetros

Você deve especificar os seguintes parâmetros para inicializar uma operação em lote:

• Uma lista das IDs de registro do contrato nas quais executar a ação fornecida: a ação pode ter qualquer um dos seguintes valores permitidos: Lembrar, Enviar, Cancelar, Excluir ou Atualizar.
• ID da sessão do usuário atual: necessário apenas para um tipo de ação de atualização.
• Registro do usuário remetente: usado para notificar o usuário por email quando o processamento em massa for concluído.

Exemplo de uso

User submitterUser = UserInfo.getUserId();

EchoSignActionBatch batch = new EchoSignActionBatch( agreementIds, 'Remind', UserInfo.getSessionId(), submitterUser); Id syncProcessId = Database.executeBatch(batch, 5); 

Lote de modelos de contrato

Usa uma consulta SOQL e uma ID de registro de modelo de contrato. A consulta é executada para obter um conjunto de registros de objeto principal, cada um dos quais é executado por meio do modelo de contrato fornecido para gerar um registro de contrato. Esta classe implementa a interface Database.Batchable do Salesforce. Ela pode processar qualquer número de registros, que serão divididos em conjuntos de 5, e processar cada conjunto como uma transação individual, o que permite que os limites do regulador sejam respeitados.

Os tipos de registro retornados pela consulta SOQL devem corresponder ao tipo de objeto principal do modelo de contrato fornecido. Para cada registro, o serviço de modelo de contrato é chamado.

O serviço em lote do Apex é exposto por meio da seguinte classe de chamada:

echosign_dev1.AgreementTemplateBatch

Parâmetros

Você deve especificar os seguintes parâmetros para inicializar uma operação em lote:

• Consulta SOQL a ser executada: deve conter a ID do registro como um campo selecionado. Outros campos são opcionais.
• ID do registro do modelo de contrato: usada com a ID do registro principal para carregar um contrato.

Exemplo de uso

String agreementTemplateId = [SELECT Id from echosign_dev1__Agreement_Template__c where Name = 'Default Template']; String soqlQuery = 'SELECT Id from Contact where Account.IsActive = true';

AgreementTemplateBatch batch = new AgreementTemplateBatch(soqlQuery, agreementTemplateId); Id syncProcessId = Database.executeBatch(batch, 5);

Lote de serviço de modelo de contrato

Usa uma lista de IDs de registro de objeto principal e o tipo de objeto principal, que são consultados, e cada um deles é executado por meio do modelo de contrato fornecido para gerar um registro de contrato. Esta classe implementa a interface Database.Batchabledo Salesforce. Ela pode processar qualquer número de registros, que serão divididos em conjuntos de 5, e processar cada conjunto como uma transação individual, o que permite que os limites do regulador sejam respeitados.

O tipo de objeto principal fornecido deve corresponder ao tipo de objeto principal do modelo de contrato fornecido. Para cada registro, o serviço de modelo de contrato é chamado.

O serviço em lote do Apex é exposto por meio da seguinte classe de chamada:

echosign_dev1.AgreementTemplateServiceBatch

Parâmetros

Você deve especificar os seguintes parâmetros para inicializar uma operação em lote:

• Lista de IDs do registro principal.
• ID de registro do modelo de contrato: usada em conjunto com os registros principais para carregar um contrato.
• Nome do objeto principal para consultar os registros principais.

Exemplo de uso

String agreementTemplateId = [SELECT Id from echosign_dev1__Agreement_Template__c where Name = 'Default Template'];

AgreementTemplateBatch batch = new AgreementTemplateServiceBatch(new List<Id>{'01p50000000HoMB'}, agreementTemplateId, 'Contact');
Id syncProcessId = Database.executeBatch(batch, 5);

Serviços REST

Serviço de modelo de contrato

O serviço de modelo de contrato é exposto como um serviço Web REST do Salesforce pelo pacote gerenciado. Isso permite que sistemas externos fora da organização do Salesforce carreguem contratos com base em modelos de contrato existentes. Consulte o artigo Criação de APIs REST usando o Apex REST para obter mais detalhes sobre como acessar e chamar serviços personalizados do Apex REST no Salesforce. As chamadas devem fornecer uma ID de sessão válida para autenticação e autorização.

O serviço Web é exposto pelo seguinte URL:

https://<instance_name>.salesforce.com/services/apexrest/echosign_dev1/template/load/<template_id>?masterId=<master_id>&varName1=var Value1&varName2=varValue2

ID do modelo

A última parte do URL é a ID do registro do modelo de contrato na organização atual do Salesforce que deve ser usada para carregar o contrato. Esta parte do URL é opcional. Se omitida, o modelo de contrato marcado como padrão será carregado. Se a ID do modelo for omitida e nenhuma ID de modelo de contrato padrão existir, um erro será retornado.

A ID do modelo pode estar no formato de 15 ou 18 caracteres.

ID principal

O parâmetro masterId especifica qual registro principal deve ser usado para carregar o contrato do modelo de contrato específico. Esse parâmetro é opcional, mas deve ser especificado para qualquer modelo de contrato que especifique um tipo de objeto principal e faça referência a esse objeto principal no modelo.

A ID principal pode estar no formato de 15 ou 18 caracteres.

Variáveis de tempo de execução

Quaisquer parâmetros adicionais são usados como variáveis de tempo de execução, como pares nome-valor, usados para preencher quaisquer variáveis de tempo de execução especificadas no modelo de contrato.

Resultado

O serviço Web REST retorna um objeto LoadResult que contém os seguintes campos:

• agreementId: se a operação de carregamento do contrato foi bem-sucedida, ela contém a ID do registro do contrato recém-criado.
• erro: se houve qualquer erro durante o carregamento do contrato, este campo conterá uma mensagem de erro detalhada.

Serviço em segundo plano

O recurso de serviço em segundo plano permite que os consumidores de pacotes chamem várias ações em um objeto de contrato atualizando o campo Ação em segundo plano (echosign_dev1 Background_Actions c) para o valor correspondente. Quando o valor do campo é alterado de um valor em branco ou outro valor para um dos seguintes valores, a ação é iniciada de um acionador que faz parte do pacote gerenciado da assinatura eletrônica.

• Lembrar
• Enviar
• Cancelar
• Excluir
• Atualizar

Todas as ações são executadas em um modo futuro assíncrono, portanto, o status será armazenado no campo Erro no contrato.

Alterações na compatibilidade com versões anteriores