The DocuSign Built-in Process Integration in SWSD is powerful. Getting it running requires a few steps across both DocuSign and SWSD. This guide walks through each one in detail.
What this integration does: As a part of a runbook or workflow, SWSD can trigger six DocuSign actions directly from tickets (Send Template for Signature, Create Envelope from Document, Check Envelope Status, Void Envelope, Download Completed Document, and Add Signer to Active Envelope), eliminating manual handoffs and reducing signature turnaround time.
Who should use it: If your organization uses DocuSign for contracts, NDAs, vendor agreements, or other signature workflows, this integration speeds up approvals by triggering DocuSign envelopes directly from a service request.
Business outcome: Reduce time and effort by automating the process of sending agreements out for signature directly from a service request, without manual handoffs or platform switching. This also improves compliance by ensuring signature requests are consistently triggered as part of a tracked workflow.
This feature launched in the June 16, 2026 release for Service Desk. For more about the release, see the full post.
Before diving in, here is a high-level overview of what the setup involves:
- Create a new app in DocuSign and generate an RSA keypair
- Register your SWSD redirect URI in the DocuSign app
- Create a JWT Grant credential in SWSD using your DocuSign app details
- Grant consent (one-time) so SWSD can act on behalf of your DocuSign user
- Set up the DocuSign Process Integration in SWSD and map fields to your SWSD system or custom fields
- Use the process integration inside a workflow rule, automation rule, or runbook
Prerequisites
Before you start in SWSD, you need three things from your DocuSign account:
- Integration Key
- RSA private key
- User ID
Here is how to get them.
Prerequisite access: You need DocuSign admin access to complete Steps 1–4. If you don’t have it, coordinate with your DocuSign administrator.
Step 1: Create a New App in DocuSign
Log in to your DocuSign admin console:
Go to Admin > Integrations > Apps & Keys and click "Add App and Integration Key." Give it a name (e.g., "SWSD Integration") and save. Copy the Integration Key that is generated. You will need this shortly.
Important: Create a new app specifically for SWSD. Do not reuse Integration Keys from other tools. Each tool should have its own app and keypair in DocuSign to avoid authentication conflicts.
Step 2: Generate an RSA Keypair
Within the same app, scroll to the RSA Keypairs section and click "Add RSA Keypair." DocuSign will display the private key once. Copy and save it immediately as it will not be shown again. The public key stays in DocuSign and does not need to be copied anywhere.
Step 3: Register the SWSD Redirect URI
Still in your DocuSign app, scroll to Additional Settings > Redirect URIs and add your SWSD credentials page URL.
To find your SWSD URL, go to Setup > Account > Account Summary and copy the Account URL shown there. Then append /setup/discovery_credentials to it. For example, if your SWSD URL is https://acme.samanage.com, your redirect URI would be: https://acme.samanage.com/setup/discovery_credentials
Save the URI before moving on. A mismatch here will block the consent step later.
Critical: Make sure the redirect URI in DocuSign exactly matches your SWSD URL. A mismatch will fail the consent step and stop the integration.
Step 4: Get Your User ID
In DocuSign Admin, go to Users and click on the user whose identity SWSD will use to make API calls. The User ID is a UUID (e.g., ae0a153b-ed07-4271-962f-e454a2ea6c62) visible in the user details page. Copy it.
Setting Up the Credential in SWSD
In SWSD, go to Setup > Account > Credentials and create a new credential. Select "JWT Grant Flow" as the credential type.
Fill in each field as follows:
Field | What to enter |
|---|
Authentication URL | https://account.docusign.com/oauth/token (production) or https://account-d.docusign.com/oauth/token (sandbox) |
Issuer | Your Integration Key from Step 1 |
Subject | Your User ID (UUID) from Step 4 |
Expiry | Token lifetime in seconds. DocuSign enforces a maximum of 3600 (1 hour) |
Scope | signature impersonation (auto-filled by SWSD, no need to edit) |
Private Key | The full RSA private key from Step 2, including the -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY----- lines |
Consent URL | Auto-generated by SWSD using your Issuer and Scope. No need to edit this field. |
Save the credential.
Granting Consent (One-Time Step)
Once you have filled in all fields and saved the credential, click the "Give Consent" button on the credential detail page. This is a one-time step required by DocuSign's JWT Grant flow.
Note: The Give Consent button is visible on the form before saving. Do not click it until you have saved the credential first, as SWSD needs the credential data to construct the correct consent URL.
Here is what happens when you click it:
- SWSD opens DocuSign's authorization page in your browser, constructed using your Issuer, Scope, and Consent URL
- Log in to DocuSign as the user whose User ID you entered in the Subject field
- DocuSign shows a permissions screen requesting signature and impersonation access for your app. Click Accept.
- DocuSign redirects your browser back to SWSD's credentials page. If consent was already granted previously for this app and user, DocuSign skips the permissions screen and redirects you back immediately.
- SWSD automatically completes the remaining configuration in the background
Tip: Make sure you are logged out of any personal DocuSign session before clicking Give Consent, so you authenticate as the correct service account user.
Verifying Authentication Status
Authentication Status is not shown immediately after granting consent. It appears only after you add the credential to the DocuSign Process Integration and save it. The status starts at "Waiting" and updates to "Authenticated" the first time a workflow triggers a DocuSign action using these credentials.
Status | What it means |
|---|
Authenticated | SWSD successfully obtained an access token from DocuSign. The credential is working. |
Waiting | The integration has not been triggered yet. Status updates after the first workflow action runs. |
Failed | The token request failed. Check your credential fields and retry consent. Verify your Issuer (Integration Key), Subject (User ID), and Private Key exactly match what you copied from DocuSign. Then click ’Give Consent’ again. |
Setting Up the DocuSign Built-in Process Integration
In SWSD, go to Setup > Integrations > Process Integrations and select DocuSign from the list.
Step 1: Set the Authentication Method
On the DocuSign Process Integration page, set the Authentication Method to JWT Grant Flow.
Step 2: Select Your Credential
In the Credential field, select the credential you configured in the previous section. This connects the process integration to your DocuSign app.
Step 3: Choose Actions
Select the DocuSign actions you want to make available in workflows. For example, "Create Envelope from Document" sends a document from a SWSD ticket to a recipient for signature.
Step 4: Map SWSD Fields
For each action, map the input fields to the corresponding SWSD fields. Each DocuSign field must be mapped to either a SWSD system field (such as requester name, requester email, or attachments) or a custom field you have created. This mapping tells SWSD what data to pull from the ticket and pass to DocuSign when the action runs.
Here is a worked example using the Create Envelope from Document action, which sends a document attached to a SWSD ticket to a recipient for signature. The action exposes the following mandatory fields:
DocuSign Field | What it is | Data Type in SWSD |
|---|
Account ID | The DocuSign account to use | Text |
Signer 1 Email | Email address of the person who needs to sign | Text |
Signer 1 Name | Display name of the signer | Text |
Signer 1 Recipient ID | A numeric ID DocuSign uses to track this recipient within the envelope. 1 for a single signer | Text |
Signer 1 Routing Order | The order in which this signer receives the envelope relative to other recipients. 1 for a single signer. If you have multiple signers, this controls the sequence in which each person receives the document. | Text |
Documents | The file to send for signature | Attachment |
Email Subject | The subject line of the email DocuSign sends to the signer | Text |
Status | Controls whether the envelope is sent immediately or saved as a draft | - |
The fields listed above are the mandatory ones, shown by default. DocuSign supports additional fields beyond these — for example, multiple signers, CC recipients, custom email body text, and more. To access them, click Add / Remove Custom Fields in the action setup and map them to the corresponding SWSD fields.
Step 5: Save
Save the process integration. The credential you selected will now appear under "Places using this credential" on the credential detail page, with an Authentication Status of "Waiting." The status updates to "Authenticated" after the first workflow action runs successfully.
Once saved, the DocuSign action is available to add to SWSD workflow rules.
Adding the DocuSign Action in a Workflow
Once the process integration is saved, the DocuSign action is available inside SWSD workflow rules, automation rules, and runbooks. Here is a worked example using the "Send NDA for Signature" service catalog item.
Example: Send NDA for Signature
In this example, a procurement team member submits a service request to send an NDA to a vendor contact for signature. The requester fills in three fields — Vendor Contact Name, Vendor Contact Email, and NDA Document.
The remaining DocuSign fields — Account ID, Recipient ID, Routing Order, Email Subject, and Status — are set automatically in the background via form logic and a Set Value process action, so the requester never sees or touches them.
Step 1: Configure Form Logic to Hide Background Fields
On the service catalog item, use Form Logic to hide the fields that the requester should never see or touch — DocuSign Account ID, Recipient ID, Routing Order, and Email Subject. These fields need to exist on the form so they can hold values, but they needn’t be visible to the requester.
Step 2: Add an Update Record Process Step to Set Background Values
Navigate to the Process tab, add an Update Record process step to set the values for the hidden fields. This step runs automatically when the service request is submitted, populating the fields with the correct values before they are passed to DocuSign.
In this example:
- DocuSign Account ID is set to the account ID from your credential
- DocuSign Email Subject is set to "Please review and sign the NDA from Acme Corp"
- DocuSign Recipient ID is set to 1 — since there is only one signer in this example, 1 is sufficient as a local identifier for the recipient within the envelope
- DocuSign Routing Order is set to 1 — since there is only one signer, routing order is 1 by default. If you have multiple signers, this controls the sequence in which each person receives the document
Step 3: Add the DocuSign Process Action
After the Update Record step, add a new process action:
- Click Add Action and select Process Integration as the action type
- In the Integration dropdown, select DocuSign
- In the Action dropdown, select Create Envelope from Document
- The field mapping is pre-filled from what you configured in Setup > Integrations > Process Integrations. Review the mapping and adjust it here if needed.
Critical: Every SWSD field you map to a DocuSign parameter must be a field that exists on the service catalog item used to trigger this workflow. The fields are assigned values at the time the workflow runs for that specific service request. If a mapped field is not part of that service catalog item, it will not be assigned a value, and SWSD will pass an empty value to DocuSign for that parameter. Depending on the parameter, this will either cause the DocuSign action to fail with an INVALID_REQUEST_BODY error, or result in the envelope being created with missing information.
The field mapping in this example:
- Account ID maps to DocuSign Account ID (hidden, set by the Update Record step)
- Documents maps to NDA Document (attached by the requester)
- Signer 1 Email maps to Vendor Contact Email (entered by the requester)
- Signer 1 Name maps to Vendor Contact Name (entered by the requester)
- Signer 1 Recipient ID maps to DocuSign Recipient ID (hidden, set by the Update Record step)
- Signer 1 Routing Order maps to DocuSign Routing Order (hidden, set by the Update Record step)
- Email Subject maps to DocuSign Email Subject (hidden, set by the Update Record step)
- Status is set to sent so the envelope is dispatched immediately
When the service request is submitted, SWSD runs the Update Record step first to populate the hidden fields, then calls the DocuSign API to create and send the envelope. The vendor contact receives an email from DocuSign with a link to review and sign the NDA.
Submitting the Service Request
With the workflow configured, here is what the end-to-end experience looks like:
Step 1: Fill and Submit the Service Request Form
The requester chooses the "Send NDA for Signature" request in the portal and fills in the three visible fields: Vendor Contact Name, Vendor Contact Email, and NDA Document.
All other fields (Account ID, Recipient ID, Routing Order, Email Subject, and Status) are hidden and require no input from the requester.
Step 2: Submit and Confirm
Once the requester submits the form, SWSD runs the Update Record step to populate the background fields, then fires the DocuSign process action. A success message is displayed under the Process tab on the service request confirming the action completed.
Step 3: Envelope Created in DocuSign
The envelope is created in DocuSign and dispatched immediately. It appears under Agreements > Sent in DocuSign, and the vendor receives an email from DocuSign with a link to review and sign the NDA.
Troubleshooting Quick Reference
Symptom | Likely Cause | Fix |
|---|
Redirect URI error during Give Consent | SWSD redirect URI not registered in DocuSign app | Add the correct URI under Admin > Integrations > Apps & Keys > Additional Settings > Redirect URIs |
Authentication Status stays at Waiting after a workflow action has run | Credential fields are incorrect, causing the token request to fail | Check that the Private Key in SWSD belongs to the RSA keypair in the same DocuSign app as the Integration Key, and that the Subject (User ID) matches the user who granted consent |
USER_DOES_NOT_BELONG_TO_SPECIFIED_ACCOUNT error when workflow runs | The Account ID and User ID (Subject) belong to different DocuSign accounts | Verify that the Account ID in your SWSD custom field matches the account where your service account user (Subject) is a member. Re-run Give Consent if needed to refresh the stored Account ID. |
INVALID_REQUEST_BODY error when workflow runs | Wrong file type attached, or Recipient ID / Routing Order left empty | Attach a PDF or Word (.docx) file — DocuSign does not accept other formats. Also confirm that Recipient ID and Routing Order are set to numeric values (e.g. 1) via your Update Record action before the DocuSign action fires. |
Envelope not visible in DocuSign after a successful workflow action | Viewing the wrong DocuSign account | Confirm you are logged into the DocuSign account matching the Account ID in your SWSD credential. If Status was set to sent, the envelope appears under Agreements > Sent. If set to created, it appears under Agreements > Drafts. |
