Adobe Acrobat Sign for Salesforce: Руководство для разработчиков

Обзор

Adobe Acrobat Sign для Salesforce: руководство для разработчиков призвано помочь разработчикам Salesforce узнать об объектах и параметрах, необходимых для интеграции вашего пакета Salesforce с Adobe Acrobat Sign.

Дополнительные сведения см. в следующих разделах:

• Руководство разработчика
• Порядок обновлений
• Службы Apex
• Службы API
• Службы пакетной обработки Apex
• Пакет шаблонов соглашения
• Пакетная служба шаблонов соглашений
• Службы REST
• Фоновые службы
• Изменения обратной совместимости

Руководство разработчика

• Если вам нужно знать, когда соглашение полностью подписано, реализуйте триггер Apex на объекте echosign_dev1__SIGN_Agreement__c, после или до обновления (в зависимости от сценария использования и требований). Когда поле echosign_dev1__Status__c изменится на Подписано или Утверждено или другие окончательные статусы, соглашение будет завершено. 
• Если вам нужно знать, когда каждый отдельный подписанный PDF вставлен, например, если вам нужно получить каждый промежуточный подписанный PDF, то реализуйте Apex триггер на объектах Attachment или ContentVersion, после вставки, и следите за родительским соглашением и именем, которое заканчивается на «- signed.pdf» или «- approved.pdf» или другим окончательным статусом.
• Если вам нужно знать, когда отдельный получатель подписал или одобрил, реализуйте триггер Apex на объекте echosign_dev1__SIGN_Recipients__c, после или до обновления (в зависимости от сценария использования и требований). Когда поле echosign_dev1__Status__c изменит статус Подписано или Утверждено или другие окончательные статусы, получатель будет завершен.  
• Если вам нужно знать, когда происходит определенное событие, которое является частью процесса подписания, например, договор отправлен на подпись или отправлено напоминание, можно создать триггер на объекте событий договора (echosign_dev1__SIGN_AgreementEvent__c) и проверить тип события.
• Имена окончательного статуса соглашения для завершенного соглашения следующие: «Подписано», «Одобрено», «Принято», «Форма заполнена» и «Доставлено».
  
• Имена статусов окончательного соглашения для расторгнутого соглашения следующие: «Отменено/отказано», «Отменено/отказано», «Истекло».

Порядок обновлений

В версии 21 порядок обновлений изменился. Ниже приведена последовательность обновления соглашения и связанных с ним объектов:

1. Вложения 
2. Получатели 
3. Документ (состояние и другие атрибуты)
4. События соглашения 
5. Каналы Chatter 

Службы Apex

Используемый метод Apex

Начиная с Acrobat Sign for Salesforce V 21.0, все асинхронные процессы (включая автоматические обновления и сопоставления данных) используют метод Queueable вместо метода Future, как рекомендует Salesforce.
С этим изменением все задания настройки, которые добавляются в очередь Salesforce для процесса автоматического обновления или сопоставления данных, будут завершаться с ошибкой: "System.LimitException: Too many queueable jobs added to queue:2."

Сбой происходит потому, что процесс с возможностью постановки в очередь может добавить только одно дочернее задание с возможностью постановки в очередь, которое уже занято Acrobat Sign. Подробности см. в разделе Лимиты очередей Apex. 

Если состояние соглашения не изменяется или сопоставление данных выполняется некорректно, может отобразиться следующая ошибка: «При создании цепочки заданий можно добавить только одно задание из выполняемого задания с помощью System.enqueueJob. Это означает, что у каждого родительского задания, добавляемого в очередь, может быть только одно дочернее задание. Запуск нескольких дочерних заданий из одного и того же задания, добавляемого в очередь, не поддерживается».

Чтобы устранить эту ошибку, найдите ошибочный триггер, построитель процесса или рабочий процесс и деактивируйте его или переключите его на использование синхронного вызова или запланируйте его на более позднее время.

Служба шаблона соглашения

Служба шаблона соглашения отображается как глобальная служба Apex в управляемом пакете. Это позволяет коду Apex за пределами управляемого пакета загружать соглашения на основе существующих шаблонов соглашений. Класс и все открытые методы помечены как глобальные, чтобы разрешить такой доступ.

Служба Apex доступна через класс вызова: echosign_dev1.AgreementTemplateService

Методы

 Конструкторы

Свойства глобального класса

Переменные среды выполнения

У глобального класса echosign_dev1.AgreementTemplateVariable есть два следующих глобальных поля:

• name: имя переменной, которое должно совпадать с именем переменной времени выполнения, настроенной в шаблоне соглашения.
• value: значение переменной, используемое во время загрузки шаблона. Значение зависит от того, где была использована переменная. Например, для получателя это должен быть идентификатор записи контакта, потенциального клиента или пользователя либо адрес электронной почты. Для переменной документа это должен быть идентификатор записи вложения.

Результат

Каждый метод либо возвращает идентификатор вновь созданной записи соглашения, либо вызывает исключение с подробным сообщением об ошибке, если что-то пошло не так во время операции загрузки.

Службы API

Служба шаблона Adobe e-Sign API раскрывается как глобальная служба Apex управляемого пакета. Это позволяет коду Apex за пределами управляемого пакета вызывать набор API Adobe e-Sign через эти обертки. Обертки значительно упрощают вызов API, поскольку потребителям не нужно создавать модель данных запроса и ответа. Также потребителям не нужно обрабатывать преобразование данных Salesforce в модели данных e-Sign. Большая часть сложности абстрагируется от потребителя. Например, для отправки соглашения потребитель просто передает идентификатор записи соглашения, а сервис обрабатывает запрос, извлекает все необходимые данные, передает их по API и анализирует результат.

Класс и все открытые методы помечены как глобальные, чтобы разрешить такой доступ.

• v17 и ниже вызывает SOAP API
• v18 и выше использует REST API.

Служба Apex доступна через следующий класс вызова: echosign_dev1.EchoSignApiService

Улучшение Apex API для других получателей

Начиная с версии 24.14 или более поздней версии, обновленный Apex API позволяет заменить или добавить дополнительных получателей, а доступ осуществляется в рамках глобального класса EchoSignApiService. Уже введено два новых элемента:

• Глобальная функция:
  

  /**

  * Input params:

  * toBeChangedRecipientId: SIGN_Recipient__c Id

  * newRecipientStr: JSON string of SIGN_Recipient__c of a new recipient for recipient replacement or alternate

  * changeType: REPLACE or ALTERNATE

  */

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

• Глобальное перечисление: RECIPIENT_CHANGE_TYPE {REPLACE, ALTERNATE}

Пример кода для вызова этого API для получателей (тип получателя: адрес электронной почты)

// сначала выполняется запрос всех получателей, связанных с соглашением

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;

// поиск получателя, которого нужно заменить или изменить

// в этом случае поиск получателя следует выполнять по адресу электронной почты.

// Дополнительные условия можно добавить для поиска получателя, которого нужно заменить или изменить

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;

    }

}

// обновление адреса электронной почты для нового получателя

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

// создание последовательности в строке json

String newRecipientStr = JSON.serialize(newRecipient);

Try {

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

} catch (Exception ex) {

    // обработка исключения и повторное выведение при необходимости

}

Методы

Внутренние классы

• Глобальный класс: DocumentHistoryEvent

• Глобальный класс: DocumentInfo
  

• Глобальный класс: ParticipantInfo

• Глобальный класс: SendDocumentResult

• Глобальный класс: SigningUrl
  

Службы пакетной обработки Apex

Представляет основные действия с соглашениями e-Sign на массовом уровне, позволяя выполнить операцию над набором соглашений. Этот класс реализует интерфейс Salesforce Database.Batchable. Он может обрабатывать любое количество записей, которые будут разбиты на наборы по 5 и обрабатывать каждый набор как отдельную транзакцию, что позволяет соблюдать ограничения губернатора.

Служба пакетной обработки Apex доступна через следующий класс вызова: echosign_dev1.EchoSignActionBatch

Параметры

Для инициализации пакетной операции необходимо указать следующие параметры.

• Список идентификаторов записей соглашений, над которыми следует выполнить указанное действие: у действия могут быть любые из поддерживаемых значений: напомнить, отправить, отменить, удалить или обновить.
• Идентификатор сеанса текущего пользователя: требуется только для типа действия «Обновить».
• Запись пользователя отправителя: используется для уведомления этого пользователя по электронной почте после завершения массовой обработки.

Пример использования

User submitterUser = UserInfo.getUserId();

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

Пакет шаблонов соглашения

Принимает SOQL-запрос и идентификатор записи шаблона соглашения. Запрос выполняется для получения набора записей основных объектов, каждая из которых затем проходит через предоставленный шаблон соглашения для создания записи соглашения. Этот класс реализует интерфейс Salesforce Database.Batchable. Он может обрабатывать любое количество записей, которые будут разбиты на наборы по 5 и обрабатывать каждый набор как отдельную транзакцию, что позволяет соблюдать ограничения губернатора.

Типы записей, возвращаемые запросом SOQL, должны соответствовать типу основного объекта шаблона соглашения. Для каждой записи вызывается служба шаблона соглашения.

Служба пакетной обработки Apex отображается через следующий класс вызова:

echosign_dev1.AgreementTemplateBatch

Параметры

Для инициализации пакетной операции необходимо указать следующие параметры.

• SOQL-запрос для выполнения: должен содержать идентификатор записи в качестве выбранного поля. Остальные поля не являются обязательными.
• Идентификатор записи шаблона соглашения: используется вместе с идентификатором основной записи для загрузки соглашения.

Пример использования

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);

Пакетная служба шаблонов соглашений

Принимает список идентификаторов записей основных объектов и тип основного объекта, которые затем запрашиваются, и каждый из них затем прогоняется через предоставленный шаблон соглашения для создания записи соглашения. Этот класс реализует интерфейс Salesforce Database.Batchable. Он может обрабатывать любое количество записей, которые будут разбиты на наборы по 5 и обрабатывать каждый набор как отдельную транзакцию, что позволяет соблюдать ограничения губернатора.

Предоставленный тип основного объекта должен соответствовать предоставленному типу основного объекта шаблона соглашения. Для каждой записи вызывается служба шаблона соглашения.

Служба пакетной обработки Apex отображается через следующий класс вызова:

echosign_dev1.AgreementTemplateServiceBatch

Параметры

Для инициализации пакетной операции необходимо указать следующие параметры.

• Список идентификаторов основных записей.
• Идентификатор записи шаблона соглашения: используется вместе с основными записями для загрузки соглашения.
• Имя основного объекта для запроса основных записей.

Пример использования

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);

Службы REST

Служба шаблона соглашения

Служба шаблонов соглашений отображается как веб-служба Salesforce REST в управляемом пакете. Это позволяет внешним системам за пределами Salesforce org загружать соглашения на основе существующих шаблонов соглашений. Обратитесь к статье Создание REST API с помощью Apex REST для получения более подробной информации о том, как получить доступ и вызвать пользовательские REST Apex сервисы из Salesforce. При вызове необходимо предоставить действительный идентификатор сеанса для аутентификации и авторизации.

Веб-служба открывается по следующему URL-адресу:

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

ID шаблона

Последняя часть URL — это ID записи шаблона соглашения в текущей организации Salesforce, которая должна использоваться для загрузки соглашения. Эта часть URL является необязательной. Если она опущена, будет загружен шаблон соглашения, отмеченный как шаблон по умолчанию. Если идентификатор шаблона опущен и не существует идентификатора шаблона соглашения по умолчанию, будет выдана ошибка.

Идентификатор шаблона может быть в формате 15 или 18 символов.

Идентификатор основной записи

Параметр masterId указывает, какая основная запись должна использоваться для загрузки соглашения из конкретного шаблона соглашения. Этот параметр является необязательным, но должен быть указан для любого шаблона соглашения, который определяет тип мастер-объекта и ссылается на этот мастер-объект в шаблоне.

Идентификатор основной записи может быть в формате 15 или 18 символов.

Переменные среды выполнения

Любые дополнительные параметры используются как переменные времени выполнения, как пары имя-значение, используемые для заполнения любых переменных времени выполнения, указанных в шаблоне соглашения.

Результат

Веб-служба REST возвращает объект LoadResult, который содержит следующие поля:

• agreementId : Если операция загрузки соглашения прошла успешно, это поле содержит идентификатор вновь созданной записи соглашения.
• error : Если во время загрузки соглашения произошла какая-либо ошибка, это поле будет содержать подробное сообщение об ошибке.

Фоновая служба

Возможность фонового обслуживания позволяет потребителям пакета вызывать различные действия над объектом соглашения путем обновления поля Background Action (echosign_dev1 Background_Actions c) до соответствующего значения. Как только значение поля изменяется с пустого значения или другого значения на одно из следующих значений, действие запускается от триггера, который является частью управляемого пакета e-Sign.

• Напомнить
• Отправить
• Отменить
• Удалить
• Обновить

Все действия выполняются в асинхронном режиме будущего, поэтому статус будет сохранен в поле Ошибка в соглашении.

Изменения обратной совместимости

Связанные материалы

• Руководство по установке Adobe Acrobat Sign для Salesforce
• Руководство по расширенной настройке Adobe Acrobat Sign для Salesforce
• Сопоставления полей и шаблоны в Adobe Acrobat Sign для Salesforce
• Руководство по обновлению Adobe Acrobat Sign для Salesforce
• Руководство пользователя Adobe Acrobat Sign для Salesforce