Overview
The Adobe Sign connector for Bizagi is available for download at Bizagi Connectors Xchange.
Through this connector, you will be able to connect your Bizagi processes to your Adobe Sign account and services.
For more information about this connector's capabilities, visit Bizagi Connectors Xchange.
|
This Connector was developed according to the contents of the API and the information about it provided by Adobe Sign. Bizagi and its subsidiaries will not provide any kind of guarantee over the content or error caused by calling the API services. Bizagi and its subsidiaries are not responsible for any loss, cost or damage consequence of the calls to Adobe Sign's API. |
Before you start
To test and use this connector, you will need:
1.Bizagi Studio previously installed.
2.The connector previously installed. For general information of the connectors refer to the the Connectors Xchange documentation. For manual installation, you can refer to the Installing and managing connectors documentation.
3.Create a Developer or Enterprise account in the Adobe website.
Create an Adobe Sign Account
To create an Adobe Sign account follow these steps:
1.Access the Adobe website and select the Create an account link.
2.In the first step of the account creation, link your Bizagi email account to the Adobe account and add a password.
3.In the second step of the account creation, you must add the following information: First and Last Name, a Date of birth, Country/Region of creation. Save your changes and agree to the Terms and Policies by clicking the Create account button.
4.Make sure to activate your account and then you can sign in to the Adobe Acrobat platform to create your API and authorization credentials. This is explained in the next section.
How to obtain your authorization credentials
After creating your Adobe account, Sign in to the Adobe Acrobat Sign website. Here you will create your API application and authorization credentials.
To get your authorization credentials you must first create an Adobe Sign application.
•Log in to your Enterprise or Developer Adobe account.
•Go to the Account tab
•On the side bar select the section Acrobat Sign API -> API Applications and then click the 
sign.
•Here you must give your application a Name, a Display Name and set it to be a PARTNER domain. Click Save to create your app.
•Check that your app is displayed on your application list.
Now to obtain your authorization credentials follow this steps:
•Again, in your Account tab go to Acrobat Sign API -> API Applications, click the app and then select Configure OAuth for Application.
•In the new window your Client ID will appear and you will be prompted for the Redirect URI field, which you must fill in with the following link: https://build.bizagi.com/redirectOauth2.html. In the Enabled Scopes section, check all the checkboxes and make sure to select the Account option in the Modifier dropdown. Once completed, click Save.
•Then click the View / Edit option.
•Copy the Application ID (Client ID) and Client Secret from your app.
Connector configuration
To configure the connector (in particular its authentication parameters), follow the steps presented at the Configuration chapter in the Installing and managing connectors documentation.
For this configuration, consider the following authentication parameters:
•Authentication method: Custom
•INTEGRATION_KEY: Key needed to integrate to your Adobe Sign app. Its the key obtained in the last section.
Using the connector
This connector features a set of methods which lets you use Adobe Sign's API services to take advantage of their capabilities.
To learn overall how/where to configure the use of a connector, refer to the Using Connectors documentation.
When using the connector, keep in mind they may need input or output configurations. The following images show examples of how to map the inputs or outputs of a method.
Available actions
Upload a document (transient)
This action uploads a document and obtains the document's ID. The document this action uploaded through this call is referred to as transient since it is available only for 7 days after the this action upload. The returned transient document ID can be used in the API calls where the uploaded file needs to be referred.
To configure its inputs, take into account the following descriptions:
• File-Name (String - Required): name of the file to upload. Maximum number of characters in the name is restricted to 255.
• File (String - Required): file contents as a base64 string.
• Mime-Type (String): the MIME (Multipurpose Internet Mail Extension) type of the document being uploaded. If not specified here then mime type is picked up from the file object. If mime type is not present there either then mime type is inferred from file name extension. Although this parameter is not required, it is highly recommended to set it, as Adobe Cloud can sometimes mistakenly identify the wrong file type. Supported MIME types are "application/pdf" (pdf), "application/vnd.openxmlformats-officedocument.wordprocessingml.document" (docx), "application/msword" (doc), "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" (xlsx), "application/vnd.ms-excel" (xls), "application/vnd.openxmlformats-officedocument.presentationml.presentation" (pptx), "application/vnd.ms-powerpoint" (ppt), "text/plain" (txt), "application/rtf" (rtf), "image/jpeg" (jpg y jpeg), "image/png" (png), "image/bmp" (bmp), "image/gif" (gif) and "image/tiff" (tiff). Use the text between the quotation marks.
To configure the outputs of this action, you can map the output object to the corresponding entity in Bizagi and make sure you map the attributes of the entity appropriately.
•transientDocumentId (String): unique identifier of the uploaded document that can be used in an agreement creation call
For more information, refer to Adobe Sign's official documentation about transientDocumentId.
List agreements
This action retrieves agreements for the user.
To configure its inputs, take into account the following descriptions:
• showHiddenAgreements (Boolean): query parameter to fetch all the hidden agreements along with the visible agreements. Default value is false.
• cursor (String): used to navigate through the pages. If not provided, returns the first page.
• pageSize (Integer): number of intended items in the response page. If not provided, it is decided by the application settings.
To configure the outputs of this action, you can map the output array to the corresponding collection in Bizagi and make sure you map the attributes of the entity appropriately.
•userAgreementList (Collection): collection with the user agreements, which contains the following information:
oid (String): ID of the agreement
oname (String): name of the agreement
ostatus (String): server generated attribute which provides the detailed status of an agreement. Possible values for this attribute are: ['WAITING_FOR_MY_SIGNATURE' or 'WAITING_FOR_MY_APPROVAL' or 'WAITING_FOR_MY_DELEGATION' or 'WAITING_FOR_MY_ACKNOWLEDGEMENT' or 'WAITING_FOR_MY_ACCEPTANCE' or 'WAITING_FOR_MY_FORM_FILLING' or 'OUT_FOR_SIGNATURE' or 'OUT_FOR_APPROVAL' or 'OUT_FOR_DELIVERY' or 'OUT_FOR_ACCEPTANCE' or 'OUT_FOR_FORM_FILLING' or 'SIGNED' or 'APPROVED' or 'FORM_FILLED' or 'DELIVERED' or 'ACCEPTED' or 'ARCHIVED' or 'CANCELLED' or 'EXPIRED' or 'WAITING_FOR_AUTHORING' or 'WAITING_FOR_PREFILL' or 'DRAFT' or 'DOCUMENTS_NOT_YET_PROCESSED' or 'WAITING_FOR_MY_VERIFICATION' or 'WAITING_FOR_VERIFICATION'].
oesign (Boolean): true if this is an e-sign document
olatestVersionId (String): a version ID which uniquely identifies the current version of the agreement.
ohidden (Boolean): true if agreement is hidden for the user.
odisplayDate (Date): the display date for the agreement.
•nextCursor (String): used to navigate to the next page. If not returned, there are no further pages.
For more information, refer to Adobe Sign's official documentation about getAllAgreements.
Create an agreement
This action creates an agreement. Sends it out for signatures and returns the agreementID in the response to the client.
To configure its inputs, take into account the following descriptions:
• AgreementInfo (Object - Required): information about the agreement that you want to create.
o name (String - Required): name of the agreement.
o fileInfos (Collection - Required): list of one or more files (or references to files) that will be sent out for signature. If more than one file is provided, they will be combined into one PDF before being sent out. This parameter should be a array of object in your Bizagi model.
▪transientDocumentId (String - Required): ID for a transient document that will be added to the agreement. The document should have been uploaded previously using the "Upload a document (transient)" action.
o participantSetsInfo (Collection - Required): list of one or more participants. Participants can be grouped together if their 'order' and 'role' attributes have the same value; participants that are in the same "group" are considered a participant set. If any member of the participant set takes the action that has been assigned to the set(Sign/Approve/Acknowledge etc.), the action is considered as the action taken by whole participation set.
▪email (String - Required): email of the participant.
▪order (Integer - Required): index indicating the order in which the signing group needs to sign. Eg: Signing group to sign at first place is assigned a 1 index. If approval should be the first thing to be done, then the participant with 'APPROVER' role should have order=1 and participant with'sIGNER' role should have order=2. No order should be specified for'sHARE' role.
▪role (String - Required): role assumed by all participants in the set (a set is a list of participants that have the same order and same role). Possible values are one of: ['SIGNER', 'APPROVER', 'ACCEPTOR', 'CERTIFIED_RECIPIENT', 'FORM_FILLER', 'DELEGATE_TO_SIGNER', 'DELEGATE_TO_APPROVER', 'DELEGATE_TO_ACCEPTOR', 'DELEGATE_TO_CERTIFIED_RECIPIENT', 'DELEGATE_TO_FORM_FILLER' o'sHARE']. Always use capital letters for this input.
o signatureType (String - Required): specifies the type of signature you would like to request - written or e-signature. The possible values are: 'ESIGN': Agreement needs to be signed electronically or 'WRITTEN': Agreement will be signed using handwritten signature and signed document will be uploaded into the system. Always use capital letters for this input.
ostate (String - Required): the state in which the agreement should land. Possible values are: ['AUTHORING' or 'DRAFT' or 'IN_PROCESS']. DRAFT: to incrementally build the agreement before sending out. AUTHORING : to add/edit form fields in the agreement. IN_PROCESS: to immediately send the agreement. Always use capital letters for this input.
To configure the outputs of this action, you can map the output object to the corresponding entity in Bizagi and make sure you map the attributes of the entity appropriately.
•id (String): The unique identifier of the created agreement.
For more information, refer to Adobe Sign's official documentation about createAgreement.
Retrieve agreement status
This action retrieves the current status of an agreement.
To configure its inputs, take into account the following descriptions:
• agreementId (String - Required): The agreement identifier.
To configure the outputs of this action, you can map the output object to the corresponding entity in Bizagi and make sure you map the attributes of the entity appropriately.
•id (String): agreement's identifier.
•name (String): name of the agreement.
•fileInfos (Collection): list of one or more files (or references to files) that will be sent out for signature. If more than one file is provided, they will be combined into one PDF before being sent out.
•transientDocumentId (String): ID for a transient document that will be added to the agreement. The document should have been uploaded previously using the "Upload a document (transient)" action.
•participantSetsInfo (Collection): list of one or more participants. Participants can be grouped together if their 'order' and 'role' attributes have the same value; participants that are in the same "group" are considered a participant set. If any member of the participant set takes the action that has been assigned to the set(Sign/Approve/Acknowledge etc.), the action is considered as the action taken by whole participation set.
•memberInfos (Collection): array of participants. All participants in the array belong to the same set (group).
oemail (String): email of the participant.
osecurityOption (Object): security options that apply to the participant
▪authenticationMethod (String): authentication method for the participants to have access to view and sign the document. Possible values: ['NONE' or 'PASSWORD' or 'PHONE' or 'KBA' or 'WEB_IDENTITY' or 'ADOBE_SIGN' or 'GOV_ID'].
oorder (Integer): index indicating position at which signing group needs to sign. Eg: Signing group to sign at first place is assigned a 1 index. If approval should be the first thing to be done, then the participant with 'APPROVER' role should have order=1 and participant with 'SIGNER' role should have order=2. No order should be specified for 'SHARE' role.
orole (String): role assumed by all participants in the set (in other words, all participants in the 'memberInfos' array). Possible values are one of: ['SIGNER' or 'APPROVER' or 'ACCEPTOR' or 'CERTIFIED_RECIPIENT' or 'FORM_FILLER' or 'DELEGATE_TO_SIGNER' or 'DELEGATE_TO_APPROVER' or 'DELEGATE_TO_ACCEPTOR' or 'DELEGATE_TO_CERTIFIED_RECIPIENT' or 'DELEGATE_TO_FORM_FILLER' or 'SHARE']
•signatureType (String): specifies the type of signature requested - written or e-signature. The possible values are: 'ESIGN': Agreement needs to be signed electronically or 'WRITTEN': Agreement will be signed using handwritten signature and signed document will be uploaded into the system.
•status (String): server generated attribute which provides the detailed status of an agreement. Possible values are: ['OUT_FOR_SIGNATURE' or 'OUT_FOR_DELIVERY' or 'OUT_FOR_ACCEPTANCE' or 'OUT_FOR_FORM_FILLING' or 'OUT_FOR_APPROVAL' or 'AUTHORING' or 'CANCELLED' or 'SIGNED' or 'APPROVED' or 'DELIVERED' or 'ACCEPTED' or 'FORM_FILLED' or 'EXPIRED' or 'ARCHIVED' or 'PREFILL' or 'WIDGET_WAITING_FOR_VERIFICATION' or 'DRAFT' or 'DOCUMENTS_NOT_YET_PROCESSED' or 'WAITING_FOR_FAXIN' or 'WAITING_FOR_VERIFICATION'].
•senderEmail (String): email of agreement sender.
•etag (String): ID of the agreement's version. You can use this ETag to update the state of an agreement later on,
•createdDate (Date): date when agreement was created
•locale (String): the locale associated with this agreement - specifies the language for the signing page and emails, for example en_US or fr_FR. If none specified, defaults to the language configured for the agreement sender.
•documentVisibilityEnabled (Boolean): if set to true, enable limited document visibility.
For more information, refer to Adobe Sign's official documentation about getAgreementInfo.
Update the state of an agreement
This action updates the state of an agreement. An allowed transition would follow the following sequence: DRAFT -> AUTHORING -> IN_PROCESS -> CANCELLED.
To configure its inputs, take into account the following descriptions:
• agreementId (String - Required): ID of the agreement to update its state.
• etag (String - Required): ID of the agreement's version. You can retrieve the ETag with a call to "Retrieve agreement status".
• AgreementInfo (Object - Required): information of the agreement.
o state (String - Required): the new state of the agreement. Possible values: ['AUTHORING' or 'CANCELLED' or 'IN_PROCESS']. An allowed transition would follow the following sequence: DRAFT -> AUTHORING -> IN_PROCESS -> CANCELLED. Always use capital letters for this input.
• agreementCancellationInfo (Object): cancellation information for the agreement if the new status is "CANCELLED". This is optional.
• comment (String): an optional comment describing to the recipients why you want to cancel the transaction.
• notifyOthers (Boolean): whether or not you would like the recipients to be notified that the transaction has been cancelled. The default value is false.
To configure the outputs of this action, you can map the output object to the corresponding entity in Bizagi and make sure you map the attributes of the entity appropriately.
•etag (String): the new ETag of the modified agreement.
For more information, refer to Adobe Sign's official documentation about updateAgreementState.
Retrieve documents of an agreement
This action retrieves the IDs of the documents of an agreement.
To configure its inputs, take into account the following descriptions:
• agreementId (String - Required): The agreement identifier to retrieve documents from.
To configure the outputs of this action, you can map the output array to the corresponding collection in Bizagi and make sure you map the attributes of the entity appropriately.
•documents (Collection): list of documents.
oid (String): ID of the document.
oname (String): name of the original document uploaded.
omimeType (String): MIME Type of the original file.
onumPages (Integer): number of pages in the document.
For more information, refer to Adobe Sign's official documentation about getAllDocumentsOfAgreement.
Download document of an agreement
This action downloads a document from an agreement.
To configure its inputs, take into account the following descriptions:
• agreementId (String - Required): agreement's identifier.
• documentId (String - Required): document's identifier as returned from the "Retrieve documents of an agreement" action. IMPORTANT: This ID is not the same as the transientDocumentId.
To configure the outputs of this action, you can map the output object to the corresponding entity in Bizagi and make sure you map the attributes of the entity appropriately.
•fileName (String): the name of the downloaded file.
•fileData (String): the data of the file as a base64 string.
For more information, refer to Adobe Sign's official documentation about getDocumentOfAgreement.
Download a single combined PDF
This action retrieves a single combined PDF document for the documents associated with an agreement.
To configure its inputs, take into account the following descriptions:
• agreementId (String - Required): agreement's identifier.
•options (Object): options to include in the request.
oattachSupportingDocuments (Boolean): when set to true, attach corresponding supporting documents to the signed agreement PDF. Default value of this parameter is true.
oattachAuditReport (Boolean): when set to true, attach an audit report to the signed agreement PDF. Default value is false.
To configure the outputs of this action, you can map the output object to the corresponding entity in Bizagi and make sure you map the attributes of the entity appropriately.
•fileName (String): name of the downloaded file. The name of the file will be "combined_{current time as ISO string}.pdf".
•fileData (String): The data of the file as a base64 string.
For more information, refer to Adobe Sign's official documentation about getAgreementCombinedDocument.
Retrieve form data
This action retrieves data entered into the interactive form fields of the agreement. This method gets this information using the names of the interactive form fields.
Since a PDF form can have a variable number of fields, you must configure this outputs in the connector itself.
To do this follow this steps:
1.Go to the Connector Editor in Bizagi Studio and click in the Add new connector from file or from your browser go to Bizagi connector editor and click the folder icon.
2.A file explorer appears. Import the connector into the Connector Editor by simply browsing for the AdobeSign.bizc in the folder where you extracted the connector.
3.Look for the "Retrieve form data" action in the Action panel and open it by double clicking it.
4.In the lower panel go to the output tab and add the necessary outputs by clicking the 
icon next to output list inside the outputs. You can see your newly created outputs at the bottom of the list.
5.The name of the outputs should be the names of the form fields without any white spaces, but keeping the original cases (since it is case sensitive). To avoid name conflicts, make sure the name of the form fields are unique after stripping off white spaces. For example, if the PDF form has a field named "Custom Checkbox 1", then you should add an output named "CustomCheckbox1" in this action's outputs.
6.Change the version of the connector and download this new configuration by clicking Download connector. Changing the version of the connector is important since if you try to install two connectors (configured for different files) with the same number version the later one will overwrite the previously installed one.
7.Then, import the connector into Bizagi Studio following the instructions in the Configuring the connector section.
Once the connector is installed you can configure its inputs taking into account the following descriptions:
• agreementId (String - Required): The agreement identifier.
To configure the outputs of this action, you can map the output array to the corresponding collection in Bizagi and make sure you map the attributes of the entity appropriately.
•completed (String): date the field value was entered.
•email (String): email of the person who filled this field
•role (String): role of the person who filled this field
•first (String): first name of the person who filled this field
•last (String): last name of the person who filled this field
•title (String): title of the person who filled this field
•company (String): company of the person who filled this field
•agreementId (String): ID of the agreement this field is part of. Keep in mind this field won't be returned if there isn't at least one filled that has a value.
For more information, refer to Adobe Sign's official documentation about getFrormFields.
Last Updated 9/6/2024 3:01:31 PM