Integrating Xero and AWS

This sample creates a service that will automatically retrieve records of overdue invoices from Xero, write the records to a CSV file, upload the file to Amazon S3, email the file to a specified recipient (e.g. an Account Manager), email a payment reminder to each debtor, and send an Amazon SNS notification to a specified recipient (e.g. an Accounts Director) when the total amount of overdue invoices is larger than a specified amount.

To achieve this, our Linx solution will use the Xero, Amazon S3, Amazon SNS, Email and File plugins and the Timer service contained in the File plugin.

Prerequisites

  • A Xero account has been registered with the necessary access credentials, including security certificates.

  • Contacts have been captured on Xero, including the contacts' email addresses.

  • Invoices have been created on Xero. (For the purpose of running this sample, invoices that are overdue should exist on Xero.)

  • AWS user credentials and permissions have been set up on IAM to allow the user to perform the S3 PutObject and SNS Publish functions.

  • An Amazon S3 bucket to where files can be uploaded has already been created.

  • An Amazon SNS Topic and associated Subscription have already been created.


Download

XeroInvoicesAWSnotifications.zip


To run the sample

  1. Download the sample file (XeroInvoicesAWSnotifications.zip).

  2. Open the XeroInvoicesAWSnotifications solution with Linx Designer.

  3. Click the Settings button on the toolbar.

  4. On the Settings tab enter the AWS credentials of a user that has been registered on AWS IAM and has the required permissions for accessing S3 and SNS.

    Example (where the values of the mandatory variables are presented by X’s):

    _{"Key":"XXXXXXXXXXXXX", "KeySecret":"XXXXXXXXXXXXXXXXX", "RegionEndpoint":"XXXXXXXXXX", "UserAccountNumber":"999999999999", "UserName":"XXXXXXXXXX"}_
    
  5. On the Settings tab enter the Xero access credentials.

    Example (where the values of the mandatory variables are presented by X’s):

    _{"CertificatePath":"XXXXXXXXXXXXX", "CertificatePassword":"XXXXXXXXXXXXXXXXX", "ConsumerKey":"XXXXXXXXXX", "ConsumerSecret":"XXXXXXXXXXXXXXXXX"}_
    
  6. Update all SendEmail properties.

  7. Enter the details of your S3 bucket and SNS topic in the relevant functions' properties sections.

  8. In the Properties section for the TextFileWrite function, note the Path value: c:\temp - update this value to a suitable path, or ensure that the c:\temp directory exists on your machine.

  9. In the Properties section for the Timer service, note the settings for when the timer event will execute - update these settings as required.

  10. In the Properties section for the IfElse function, note the contents of the Conditions property: GrandTotalOverdue > 50 - update the condition if required.

  11. Follow the steps provided to recreate the end-to-end implementation of the sample.


Creating the sample

The following steps can be used to re-create the solution used in this sample, or to use as a guide when deploying and running the sample:

  1. Create a Solution, Project, and Process with descriptive names.

  2. Add the following Plugins to your Solution:

    • Xero
    • Amazon S3
    • Amazon SNS
    • Email
    • File
  3. From the Utilities plugin, add the Timer service. In the Properties section provide the settings for when the Timer event should be executed.

  4. From the Linx plugin, add the Decimal type to the Timer Event and rename it to GrandTotalOverdue.

  5. From the File plugin, add the TextFileWrite function and rename it to WriteFileHeadings.

  6. From the Xero plugin, add the GetInvoices function and rename it to GetInvoicesFromXero. In the associated Properties section, ensure that the following settings are configured:

    a) Statuses - select "Authorised"

    b) Where - the following ensures that all invoices that have a due date older than today's date will be retrieved: "DueDate < DateTime({0}, {1}, {2})".FormatWith($.System.CurrentDateTime.Year, $.System.CurrentDateTime.Month, $.System.CurrentDateTime.Day)

    c) Return options - select "Item by Item"

  7. From the Xero plugin, add the GetContacts function nested under GetInvoicesFromXero. In the Properties section, the value of the Contact ID property is used to retrieve the contact details of the debtor.

  8. From the Email plugin, add the SendEmail function. The To property will be the email address of the debtor, which was returned by the GetContacts function.

  9. From the Linx plugin, add the SetValue function and rename it to SetGrandTotalValue. In the Properties section, set Target to GrandTotalOverdue, and set the Source property to add the invoice's AmountDue value to the GrandTotalOverdue value, which accumulates the total value of all overdue invoices.

  10. From the File plugin, add the TextFileWrite function and rename it to WriteFileRecords. Each record is written to the file created by WriteFileHeadings. At this point in the process all the overdue invoice records have been retrieved and written to a CSV file, while each debtor has been sent an email reminder of the overdue invoice.

  11. From the Email plugin, add the SendEmail function. In the To property, enter a specific email address. The attachment is the CSV file containing the overdue invoice records. For more details on how to set the properties of SendEmail, go here.

  12. From the Linx plugin, add the IfElse function. Set a condition named LargeGrandTotalOverdue to return True when the GrandTotalOverdue amount is larger that the specified amount (i.e. 50 - change this value if required).

  13. From the Amazon SNS plugin, add the Publish function nested under the IfElse function. In the Properties section, add the Topic ARN of a topic that has already been created on AWS SNS. The message in this sample indicates the GrandTotalOverdue amount.

  14. From the Amazon S3 plugin, add the PutObject function and rename it to UploadFile. Provide the Bucket name to where the file will be uploaded, and specify the File path of the file to upload.

  15. Debug the process

    For details on how to debug, please go here

  16. Deploy the Solution to Linx Server

    For details on how to deploy your Solution, please go here

  17. Start the Service on Linx Server by doing the following:

    a. Log in to Linx Server

    b. Select the applicable Solution

    c. Click the Start button to start the service

  18. Verify the successful execution of the Service

    To check whether your service is executing as expected, do the following:

    a. On Linx Server, check that the Event executed successfully

    b. Check that the CSV file was created in the specified folder and that the expected records were written to the file

    c. On the AWS console (S3), check that the CSV file was uploaded to the relevant S3 bucket

    d. Check that all emails and notifications were received, i.e. the reminder emails to each debtor, the email with CSV attachment to the Account Manager, and the notification email to the Accounts Director (only if the total overdue amount exceeds the specified amount)