Create a Record in Xero

Table of Contents

Overview

The xero.create() task is used to add records in any of the supported modules of your Xero account, directly from your Zoho Creator application. For example, you can create Contacts, create Items with details like account price and unit price, add your bank account details, generate invoices for sales, bills etc. To connect Zoho Creator with Xero, add a new connection from the Setup - Connections page.

Supported Modules

  • Contacts
  • Accounts
  • Items
  • Bank Accounts
  • Invoices
  • Employees

Syntax

createresponse= xero.create("xeroConnectionName", "xeroModuleName", params);

where,
<createresponse> is the map variable returned as response. It contains the details of the newly created record.
<xeroConnectioName> refers to the connection name used to connect Zoho Creator with Xero. Create a new connection from the Setup - Connections page.
<xeroModuleName> refers to the module name in Xero where the record is created.
<params> is the map variable that holds the key,value pairs. The map key is the label name in the format as specified in Xero API Guide. The map value is the field value as submitted from a Zoho Creator application.

Example - To create a record

A sample script to create a contact to Xero Contacts module is given below. Lets say we have a Zoho Creator form with fields related to Xero Contacts module. Add the following script to the required Form Actions block of this form. For example, to add a record to the Contacts module, based on the values submitted from this Zoho Creator form,

  1. Select the Form from your Dashboard page.
  2. Click on Settings - On Add - Actions on Success.
  3. Add the script to the editor area.
  4. Click on Save Script to save the script definition.

    //Declare Map Variable to hold the contact details

    contact = map();
    details = map();
    address = map();
    phone = map();

    //Add the contact details to the map variable
    //The left parameter (Name) is a Form Field and the right parameter (John Smith) is the assigned value
    details.put("Name", "John Smith");
    details.put("FirstName", "John");
    details.put("LastName", "Smith");
    details.put("EmailAddress","john.smith@zillum.com");
    address.put("AddressLine1","805 Las Cimas Pkwy");
    address.put("AddressLine2","Suite 380");
    address.put("City","Austin");
    list_address = List();
    list_address.add(address);
    details.put("Addresses",list_address);
    phone.put("PhoneType","MOBILE");
    phone.put("PhoneNumber","1234567890");
    list_phone = List();
    list_phone.add(phone);
    details.put("Phones",list_phone);
    contact.put("Contact", details)

    //creating the contact in Xero Contacts module with connection name "Xero"
    createresponse = xero.create("Xero", "contacts", contact);

  5. Upon submitting the form, a record gets created in Xero Contacts module with Name - "John Smith", First name - "John" and Last name - "Smith".

Get the Record ID

You can retrieve the newly added record ID by adding the following script in the required action block of your Zoho Creator form. This script must follow the script added to create a new record.

contactList = createresponse.get("Contacts").toJSONList();
for each resMaptemp in contactList
{
resMap = resMaptemp.toMap();
id = resMap.get("ContactID");
}

Note

  • You can add the script directly to the editor area by selecting Free-flow scripting link displayed on the top-right corner of the script builder ( or ) use the drag-and-drop functionality in Script Builder.
  • In the above example, we have specified the param values directly within quotes. To fetch the param values from a Zoho Creator form, specify the field deluge name used in the form. For example, if First_Name is the Field Deluge name, the key value pair should be specified in the following format: ("FirstName", First_Name)

Response Format

The response returned by Xero will be in the format given below:

{
"Status":"OK",
"ProviderName":"Zoho Creator Local",
"Contacts":"[{"Phones":[
{
"PhoneNumber":"1234567890",
"PhoneType":"MOBILE"
}
],
"Addresses":[
{
"AddressLine1":"805 Las Cimas Pkwy",

"AddressLine2":"Suite 380",
"City":"Austin"
}
],
"UpdatedDateUTC":"/Date(1415738518863+1300)/",
"ContactStatus":"ACTIVE",
"IsCustomer":false,
"ContactPersons":[

],
"LastName":"Smith",
"SalesTrackingCategories":[

],
"Name":"John Smith",
"PurchasesTrackingCategories":[

],
"ContactID":"4f80a131-3943-4dc3-9dd6-032d727ccdad",
"EmailAddress":"",
"FirstName":"John",
"ContactGroups":[

],
"BankAccountDetails":"",
"HasValidationErrors":false,
"IsSupplier":false
}
]","Id":"950b5212-b613-453e-bf31-8aea276d3702",
"DateTimeUTC":"/Date(1415785318879)/"
}

If the execution fails due to incorrect parameter value,the response will be in the following format:

{
"Message":"A validation exception occurred",
"Type":"ValidationException",
"Elements":"[{"Phones":[

],
"Addresses":[

],
"Attachments":[

],
"LastName":"Smith",
"ContactPersons":[

],
"Warnings":[

],
"ValidationErrors":[
{
"Message":"The contact name John Smith is already assigned to another contact.
The contact name must be unique across all active contacts."

}
],
"SalesTrackingCategories":[

],
"Name":"John Smith",
"PurchasesTrackingCategories":[

],
"ContactID":"00000000-0000-0000-0000-000000000000",
"ContactGroups":[

],
"HasValidationErrors":true
}
]","ErrorNumber":10
}

Using Script Builder

To add the script using the drag-n-drop functionality in Script Builder,

  1. Select the Form from your Dashboard page
  2. Click on Settings - On Add - Actions on Success
  3. Click on Script Builder from the top-right corner of the page.
  4. Drag and drop the call function in the editor box.
  5. Select Integration tasks.
  6. Select Service as Xero.
  7. Select Function as Create Record.
  8. Select the Connection Name to connect with Xero. Click on +Create to create a new connection or create a new connection from the Setup - Connections page.
  9. Select the required Module name in Xero.
  10. Select the map variable that holds the key-value pairs for the create request (or) click on "New Map" to add key-value pairs for the create request.
  11. Specify the response variable that will hold the response returned by Xero.
  12. Click on Done to insert the call function task.


Upon submission of the form, the record gets added to selected module in Xero. The response variable will contain the response returned by Xero.

Note

  • The key-value pairs displayed will differ based on the module selected.

Share this post : FacebookTwitter