Home / / Referral Format Changes (November 2023)

Referral Format Changes (November 2023)

1434 views 3 min , 33 sec read

The BYDA Referral Service will be making some small changes to the format of referrals sent to members at the end of November 2023. This article provides a technical description of the changes and is targeted at IT specialists and application developers.

A webinar describing the changes can be accessed on YouTube. It is recommended you watch the webinar before reviewing the details in this article.

The presentation slides used in this webinar are also available to download.

There are three options available for receiving referrals from the BYDA Referral Service. These options are selected in the member referral configuration screen in SmarterWX Sentinel.

  1. Web Hook – register a web service endpoint to receive a JSON payload describing the referral.
  2. Legacy Email – provide an email address to receive a collection of attachments describing the referral.
  3. SmarterWX Automate – this is a built-in direct integration available for users of the BYDA automation service. No changes are required for users of SmarterWX Automate.

The remainder of this article provides technical details on the Web Hook and Legacy Email options. Example payloads are also included.

Starting in late October, a testing environment will be available. For access to the testing environment please contact the BYDA Helpdesk at support@byda.com.au.

Web Hook

An Open API specification for the referral web hook can be downloaded here. The specification includes detailed descriptions of all objects and attributes included in the referral JSON payload.

An example of a referral using the new JSON format can be found here.

The changes are: –

  • messageVersion updated to 2.1.0.0.
  • New fields added to the User object: verificationStatus, subscriptionStatus, preferredDataFormat.
  • New field added to the Enquiry object: projectReference.
  • New option added to the Enquiry.source attribute: added API as an option indicating that the enquiry was lodged through an API automation.
  • New object included in the referral when source is AUTORENEW: autoRenew.

Legacy Email

Note: it is strongly recommended that automated referral response systems still using legacy email referrals start to transition to using web hooks for referrals. Future updates may not be applied to the legacy email option.

Referrals sent using the legacy email option, can include a collection of different attachments: –

  • Email Body – machine readable content describing the referral.
  • XML Attachment – XML content describing the referral.
  • PDF Attachment – human-readable representation of the referral.
  • GML Attachment – no change.
  • KML Attachment – no change.
  • GIF Attachment – no change.

Details of the technical changes to the Email Body, XML Attachment and PDF Attachment are described below, including examples of the new formats.

Sending Email Address

The sender email address for legacy email referrals will also change. The current sender is Referrals@1100.com.au. This will change to referrals@byda.com.au. You might want to discuss whitelisting the new address with your IT team to avoid any potential spam filtering.

To avoid inadvertently triggering blacklisting of the new sender, the sender email address change will be implemented gradually (a process known as warming up the email address). During the first 10-14 days after go live, you might receive referral emails from both addresses with the new referrals@byda.com.au slowly increasing in volume.

If you intend to use UAT, the sender email address will be referrals-uat@byda.com.au.

Email Body

An example of a referral using the new email body can be found here.

The changes are: –

  • The message version number is updated to 2.1.0.0.
  • References to Dial Before You Dig and DBYD are replaced with Before You Dig Australia (BYDA).
  • The Enquiry Medium field will contain one of API, AUTORENEW, BULK, MOBILE, WEB.
  • Three unused fields are being removed:
    • TO
    • LARGE SCALE
    • DBYDMESSAGE
  • Three new fields added to REFERRAL DETAILS section:
    • PROJECT REFERENCE: For future use – will be blank.
    • AUTO RENEW FIRST JOB NUMBER: If this enquiry was created by auto-renew, contains the Job Number of the initial enquiry in the sequence created by the user.
    • AUTO RENEW FIRST SEQUENCE NO: If this enquiry was created by auto-renew, contains the Sequence No of the initial referral in the sequence created by the user.
  • Seven new fields added to CALLER DETAILS section:
    • VERIFICATION STATUS: For future use – will always contain the value “EmailOnly”.
    • SUBSCRIPTION STATUS: For future use – will always contain the value “None”.
    • PREFERRED DATA FORMAT: For future use – will always contain the value “None”.
    • LODGED BY NAME: For future use – will be blank.
    • LODGED BY EMAIL: For future use – will be blank.
    • LODGED BY COMPANY: For future use – will be blank.
    • LODGED BY TELEPHONE: For future use – will be blank.

XML Attachment

An example of an XML Attachment using the new format can be found here.

The XML Style Descriptor for the new format can be found here.

The changes are: –

  • The message version number is updated to 2.1.0.0.
  • References to Dial Before You Dig and DBYD are replaced with Before You Dig Australia (BYDA).
  • The EnquiryMedium field will contain one of API, AUTORENEW, BULK, MOBILE, WEB.
  • One unused field is being removed:
    • ReferralDetails.To
  • Three new fields added to ReferralDetails section will be present on all referrals:
    • ProjectReference: For future use – will be blank.
    • AutoRenewFirstJobNumber: If this enquiry was created by auto-renew, contains the Job Number of the initial enquiry in the sequence created by the user. Otherwise, blank.
    • AutoRenewFirstSequenceNumber: If this enquiry was created by auto-renew, contains the Sequence Number of the initial referral in the sequence created by the user. Otherwise, blank.
  • Seven new fields added to CustomerDetails section will be present on all referrals:
    • VerificationStatus: For future use – will always contain the value “EmailOnly”.
    • SubscriptionStatus: For future use – will always contain the value “None”.
    • PreferredDataFormat: For future use – will always contain the value “None”.
    • LodgedByName: For future use – will be blank.
    • LodgedByEmail: For future use – will be blank.
    • LodgedByCompany: For future use – will be blank.
    • LodgedByTelephone: For future use – will be blank.

PDF Attachment

An example of a PDF Attachment using the new format can be found here.

The changes are: –

  • The message version number in the document footer is updated to V4.1.
  • If this enquiry was created by auto-renew, a new section is added below the map to provide details of the first enquiry/referral in the sequence.
    The To: and Email: fields have been removed from the Utility Details section.
  • The Enquiry Medium will contain one of API, AUTORENEW, BULK, MOBILE, WEB.
  • One new field is added to the Enquiry Details section:
    • Project Reference: For future use – will contain value “Not Supplied”.