Xero for Docusign IAM

Xero Quick Start

1. Installation

• Install the Xero app from the Docusign App Center.
• During installation, grant the required permissions.
• After installing, click Connect Account to link your Xero organization.

2. Creating a Connection

• You will be prompted to choose a connection type:

  • Shared — accessible by the whole team (recommended).
  • Private — accessible only by you.

• Give your connection a clear name (e.g., "Xero Demo Company").

• Log in to Xero to authorize the connection.

3. Creating a Workflow

• Navigate to Agreements > Workflows.
• Click Create Workflow to start building.

4. Available Xero Actions

The app provides three main actions to use inside your workflow:

• Read from Xero — retrieve data from the Xero system (e.g., Contact details).
• Writeback to Xero — update existing records or create new data in Xero.
• File Upload — attach a specific file (like a signed agreement) to a Xero Contact.

5. Important File Upload Configuration Nuances

• File Upload Location: When configuring the File Upload step, you must set the Drive to Contacts.
• How to set it: Click New Subfolder > Add Variable and select the ID retrieved from the "Read from Xero" step.
• New Sub Folder Variable: For the New Folder, you must use the Contact ID variable (not the name).

Known Behaviors & Limitations

This page covers important behaviors and limitations of the Xero integration in Workflow Builder that you should be aware of when building your workflows. Understanding these nuances will help you avoid common configuration mistakes and set up your workflows correctly from the start.

“OR” operator

The "OR" operator has important limitations:

• If the "IF" condition matches a contact → that contact is used
• If "IF" doesn't match → falls back to "OR" conditions, the first matched record is used
• If all "OR" conditions point to the same contact → works correctly
• If "OR" conditions match different contacts → the workflow fails with 400: "Found multiple records for the given search query".
• If an "OR" field value is empty at runtime → the workflow will fail. Make sure all fields used in "OR" conditions are always populated. If a field might be empty (e.g., optional web form fields), avoid using it as an "OR" condition

Case Sensitivity

Although Xero itself is not case-sensitive when searching contacts, we recommend always using the exact name as it appears in Xero. This ensures consistent and predictable behavior across all workflow steps.

Special Characters in Contact Names

The following special characters are confirmed to work correctly in contact names: /, &, ', @, +, ,, ., -, ?, (, )

If a contact name contains other special characters not listed above, unexpected errors may occur. In such cases, please contact support.

1. Installation and Configuration

Prerequisites

Before starting, ensure that:

• You are logged in to a Xero account with the required permissions.
• You are logged in to a Docusign account with Admin rights to install and manage applications.

How to Install the App

1. Open the Docusign App Center.
2. Search for and locate the Xero application.
3. Click the Install App button to begin.
4. During installation, grant the required permissions when prompted.

Connecting Your Account

Once the app is installed, you need to authorize the connection between Docusign and Xero.

1. Initiate Connection: After installation, click the Connect Account button on the app screen.  

2. Select Account Type: You will be prompted to choose the connection visibility:

   • Shared (Recommended): The connection is accessible by the whole team in Docusign. This is best for collaborative workflows.
   • Private: The connection is accessible only by you.

3. Name the Connection: Enter a clear name for your connection (e.g., "Xero Demo Company"). This name will be displayed later in Workflow steps, so make it easily identifiable.  

4. Authorize with Xero: Click Login to proceed to Xero.

   • Select the organization you want to connect.

   • Troubleshooting: If you are already logged in and your organization appears "greyed out" or inactive in the list, click "Continue with [N] organisations" or select "Select another organisation" from the dropdown menu to re-authorize access.

     

5. Completion: You will be redirected back to the Docusign App Center. The app status should now show as Installed, and the connection is ready to use.

Managing Connections

You can edit, delete, or add new connections at any time without reinstalling the app.

To access connection settings:

1. Go to the Docusign App Center > Installed Apps.
2. Find the Xero app and click the Manage dropdown or the three dots menu.
3. Select Manage Connections.

 Available Actions:

• Edit Name: Rename the connection for better clarity.
• Reconnect: Force a reconnection to refresh tokens or update permissions.
• Delete: Remove the connection (Warning: This may break workflows using this connection).

Adding a New Connection

If you need to connect to a different Xero company (e.g., for a different workflow), click + Add New Connection inside the Manage Connections screen. Follow the same setup steps as the initial installation.

2. How to Use the App

he Xero app enables you to work with Xero data directly within Docusign Workflows. Using this app, you can create workflows that read data from Xero, update Xero records, and automatically attach signed documents as part of an automated process.

Create a Workflow Builder To start using the integration, you first need to create a Workflow in Docusign.

1. Log in to Docusign.
2. Navigate to Agreements → Workflows.
3. Click Create Workflow.
4. Build your workflow using the available steps, including Xero actions provided by the app.
5. Publish the workflow when ready.

Available Xero Actions

Within the Workflow Builder, the Xero app provides actions to interact with your data. These actions allow Xero to act as both a source and a destination within the same workflow.

The following actions are available:

• Read from Xero: Retrieve data from the Xero system (e.g., Contact details).
• Writeback to Xero: Update existing records or create new data in Xero based on the workflow setup.
• File Upload: Attach a specific file (e.g., a signed agreement or W-9 form) to a Xero Contact.

Configuring Actions: Workflow Start

In this documentation, we will use object_id as the workflow startup variable. This is a common pattern when triggering workflows from an external system via API.

To configure the workflow trigger:

1. Select From an API Call as the workflow start method.
2. Create a variable named object_id (Type: Text).
3. Choose Automated process as the trigger type.

This configuration allows external systems to trigger the workflow and pass a specific identifier (like a Xero Contact ID) into the object_id variable. This variable can then be used in subsequent steps (like "Read from Xero") to identify which record to process.

3. Configuring "Read from Xero"

The Read from Xero step allows a workflow to retrieve data for a specific Xero Contact. To do this correctly, the workflow must be able to identify which Xero entity it should work with.

Step Overview

Configuring this step involves three main stages:

1. Selecting the Xero connection and object.
2. Choosing which fields to read (retrieve).
3. Defining the rule to identify the target record.

---

1. Add the Step to Workflow

1. In your workflow builder, click + Add Step.
2. Search for and select Read from Xero.
3. Once the block appears, click Configure to start the setup.

2. Configure Connection and Object

You will be prompted to select where to read data from.

1. Connection: Choose the Xero connection you created earlier (e.g., "Xero Demo Company").
2. Object: Select the entity type you want to work with. In this example, select Contact.
3. Click Next.

3. Select Fields

Choose the specific data points you want to retrieve from the Xero Contact.

1. Click Add or Remove Fields.
2. Select fields like Name, Email Address, Contact Number, etc..
3. These fields will become available as Workflow Variables for use in later steps.
4. Click Next.

4. Identify the Record

In this step, you define which specific Xero record the workflow should read. You do this by creating a matching rule.

Create a rule that matches a Xero field to a workflow variable:

• Xero Field: Select a unique identifier field in Xero (e.g., Account Number or Contact ID).
• Operator: Select Equal to.
• Workflow Field: Select the variable that contains the identifier (e.g., object_id, which we configured at the workflow start).

Example Logic: This rule tells the system: "Find the Xero Contact whose Account Number matches the object_id provided when the workflow started."

Note: You can use other fields for identification (e.g., Email, Name), provided they are unique enough to identify a single record.

Once configured, this step will find the correct Contact in Xero, and pull the selected data into the workflow. You can now use these variables (e.g., to pre-fill a document) in subsequent steps.

4. Configuring "Writeback to Xero"

The Writeback to Xero action allows a workflow to update existing Xero records or create new ones using data generated during the workflow execution (e.g., from a signed document or a web form).

Step Overview

This step is typically used at the end of a workflow to save results back to Xero. A common pattern:

1. Read Client data from Xero.
2. Send documents for signature using that data.
3. Receive updated information from the signer.
4. Writeback: Update the client record in Xero with the new data.

1. Add the Step to Workflow

1. In your workflow builder, click + Add Step.
2. Search for and select Writeback to Xero.
3. Click Configure to open the settings.

2. Configure Connection and Object

1. Connection: Select your Xero connection.
2. Object: Choose the entity you want to write to (e.g., Contact).

3. Choose Write Settings

Decide how the system should handle the data writing process:

• Update: Updates an existing record. Fails if no matching record is found.
• Create: Always creates a new record regardless of whether one already exists.
• Update or Create (Recommended): Smartly checks if a record exists. If yes, it updates it; if not, it creates a new one.
• Click Next.

4. Map Fields

Select which fields in Xero you want to populate with workflow data.

⚠️ Important: The Name field is mandatory in the Xero API. It is the key field used to find or create records.

1. Map the Name Field: Ensure you map the Xero Name field to a valid workflow variable (e.g., a "Name" field collected from a Web Form or the Name variable from the Read step).
2. Map Other Fields: Map any other data points you wish to update (e.g., Email, Phone).
3. Click Next.

5. Identify the Record

Finally, you must define the rule for identifying which record to write to.

Configure the rule as follows:

• Xero Field: Select Name (since it's the API key field).
• Operator: Select Equal to.
• Workflow Field: Select the corresponding workflow variable that contains the Name (e.g., Name from your Web Form).

Click Done. The step is now configured to automatically update or create Xero records when the workflow runs.

5. File Upload to Xero

The File Upload action allows a Workflow to upload and attach a file to a Xero Contact.

1. Add the File Upload Step

Add the File Upload to Xero action to your Workflow and open its configuration.

2. Select the File to Upload

You need to specify which file from the workflow should be uploaded.

Select File: Choose Combined Envelope File (or another file variable generated by previous steps).

💡 Note: If no file is available for selection, it usually means that the file was not generated in previous workflow steps. Verify that your workflow includes steps such as document preparation and signing before File Upload.

3. Choose the Upload Location

⚠️ Important: The UI uses standard "Folder/Subfolder" terminology, but in the context of Xero, this structure represents the Xero Entity Hierarchy.

To attach a file, you must first select the Drive as Contacts. Then, for the Folder, you have two ways to choose the destination:

Method A: 

Select contact from List.

You can select a specific Contact manually from the dropdown list.

• Result: The file will always be attached to this specific Contact, regardless of who is processed in the workflow.
• Use case: Useful if you want all files to go to a single central record (e.g., a generic "Admin" contact).

Method B: 

Attach to the Current Workflow Contact (Dynamic method).

You can configure the New Subfolder using a variable (Contact ID).

Please check below "How to configure" for more information.

• Result: The file will be attached to the specific contact involved in the current workflow run.
• Use case: Essential for universal workflows where you want the signed document to go to the correct client's record automatically.

How to configure Contact ID in New Subfolder:

Step 1 — Select Drive In the Select Drive dropdown, choose Contacts. This sets the target entity type for the upload. Step 2 — Add Folder Variable Under Select Folder, click New Subfolder. In the dialog (New Folder), click Add Variable. Select the variable source. Remember, we should select Contact ID! You can receive it from the Xero Read step. Choose: ID. Click Add. ✅ Result: The Folder entry will appear in the File Upload location UI and will contain the ID variable.

Final Expected Structure

After completing the steps above, your File Upload location should look like:

• Drive: Contacts
• Folder: [contacts[1] / Id]

This configuration attaches the uploaded file to the specified Contact.

4. Name the File

1. Click Next.
2. File Name: You can combine text with variables from previous steps to create a custom file name (e.g., [Contact Number] - W-9 Form).
3. Click Save.

5. Verification

If everything is set up correctly, the file will be attached to the selected contact ID.

1. Open the Contact in Xero.
2. Navigate to the Files tab to see the uploaded document.

FAQ & Troubleshooting

Here are the most common configuration issues and how to resolve them.

File Upload Issues

Q: Why must I use the "Contact ID" for the Folder name?

A: The Xero API requires a unique identifier to attach files to specific records. Names are not reliable because they can be duplicates. You must map the Folder to the ID variable (retrieved from the "Read from Xero" step). If you use a static text name for the folder, the upload will fail or go to the wrong location.

Q: I don't see any files available in the "Select File" dropdown.

A: This usually happens if the upload step is placed incorrectly in the workflow.

• Cause: The workflow hasn't generated a file yet at this stage.
• Solution: Ensure that a "Sign Document" step exists before the File Upload step .