Interfaces

API e-hub

Participants can submit and receive CATS Customer Administration and Transfer Solution. A set of procedures, principles and obligations made under the National Electricity Rules as part of Market Settlement and Transfer Solutions (MSATS), and applicable to NMI (National Metering Identifier) small and large classifications. Transactions and change their Participant User A Participant ID's users created and maintained by the Markets Portal PA in the URM. password using the API Gateway Part of AEMO's API -e-Hub used by participants and AEMO to push or pull messages using RESTful APIs. Some APIs are accessible over the internet and MarketNet.. For details, see:

Figure 132 Figure 2 Participant API gateway to AEMO e-Hub

Participant file server

CATS Transactions between participants and the MSATS Market Settlement and Transfer Solutions. The procedures published by AEMO under clause 7.2.8 of the National Electricity Rules, which include those governing the recording of financial responsibility for energy flows at a connection point, the transfer of that responsibility between market participants, and the recording of energy flows at a connection point. Web Portal or File Interface are stored in the Participant File Server The publishing point from AEMO systems to participant systems. Each participant is allocated an account and access to private and public areas. Participants are responsible for interfacing with the participant file server. in two folders:

  1. INBOX: Participants put files for MSATS in the Inbox (see Participant file server inbox to MSATS web portalPage 1).

Participants can place aseXML A standard for energy transactions in XML. A set of schemas and usage guidelines that define how data should be exchanged under FRC in the gas and electricity industries in Australia. messages in zip format directly to their Participant File Server Inbox.

  1. OUTBOX: MSATS puts aseXML messages in the Outbox (see InterfacesPage 1).

MSATS web portal

Participants can submit and receive CATS Transactions in the MSATS Web Portal interface. This interface is mostly used by participants having a limited number of files to process. For help, see Guide to MSATS Web Portal.

Participant file server inbox to MSATS web portal

Figure 133 Participant file server inbox to MSATS web portal

Participant file server outbox to MSATS web portal

MSATS web portal file upload

Participants can upload Batch A right type assigned to a participant user by their participant administrator to access a Batch (file) application CATS Transactions using the Data Load Import > Participant Inbox > Upload function. This is called Batch to Web Portal or Interactive A right type assigned to a participant user by their participant administrator to access a Web Application or API Loading). For help, see Guide to MSATS Web Portal.

Uploading Transactions using this option, places them in your Participant Inbox on the Participant File Server (see MSATS web portal file uploadPage 1).

When MSATS completes validation, you receive a response Transaction See Relevant Rules or Procedures zip file. If the data loaded successfully, the acknowledgement details are found within the <Acknowledgements> element, towards the end of the XML eXtensible Mark-up Language. file. There is only one message acknowledgement per file. Depending on the number of transactions in the file, there can be multiple Transaction Acknowledgements. For details, see MSATS to participantPage 1.

For details about how to clean up left-over files if they are not acknowledged immediately, see Acknowledgement Page 1.

Figure 134 MSATS web portal file upload

File interface (FTP)

Participants can submit and receive CATS Transactions using FTP File transfer protocol to the Participant File Server. This is called Batch to Participant File Server or Direct Loading.

This interface is mostly used by participants with many files to process by implementing an automated Batch File Interface. For help, see Guide to MSATS Participant Batcher An application providing an interface for batch transactions (files). software.

All communications use aseXML-formatted messages. When MSATS processes Transactions using the File Interface, they undergo the same validity checks as those processed using the MSATS Web Portal.

You place the Batch files in your Participant Inbox on the Participant File Server by 1 of the following methods:

  1. FTP software. For help, see Participant File Server on page Page 1.

  2. Using a back-end process such as MSATS Participant BatcherSoftware to automate the FTP loading. Use this option if you have a lot of files to process.

Direct Loading is a two-stage process. You or your IT system writes a TMP file to your Participant Inbox and then rename it to a zip file. You do not directly copy the zip file. For help, see Creating and submitting batch transactions on page Page 1.

File interface rules

To create a Change Request A transaction submitted by participants in MSATS whenever they want to create or update data held in MSATS. using the File Interface, you must adhere to the following rules:

File name format

The file name has four sections:

Section

Description

Size

Transaction Group

For NMI Discovery, the transaction group is NMID

For CATS transactions, the transaction group is CATS

4 Alphanumeric

Priority

h = High

m = Medium

l = Low

Messages within each priority group are processed in last modified order

The priority for NMI Discovery is high (h)

The priority for CATS transactions is medium (m)

1 Character

Unique ID

A unique participant-generated identifier for the file. Possibly the Participant ID.

30 Alphanumeric

Extension

The zip includes the xml file

3 characters

Example

<TransactionGroup><Priority>_<uniqueId>.extension

NMIDH_partID_1009.xml

CATS_partID_1010.xml

catsm_<Participantid>batch_<uniqueId>.zip

catsm_<Participantid>_<uniqueId>.zip

n/a

 

Transaction format

The information in this section is a guide only. For help creating an aseXML file, see the aseXML Guidelines Guidelines for the development of a Standard for Energy Transactions in XML (aseXML)..

Transaction formatPage 1 explains the information required for each Transaction.

For examples, see:

Table 96 Transaction format

Field

Format

Transaction

Participant Name

Up to 30 characters

Enter in quotes between the <From description>PART LNSP</From description> element

CR

Participant ID

Up to 15 characters

Must be CAPITALISED

Enter in quotes between the <From>SOLARISP</From> element

CR

Message Date/Time

YYYY-MM-DDTHH:MM:SS.sss

CR

Transaction Group

4 characters

Must be CAPITALISED

CR

Priority

Up to 6 characters

Must be upper case

Options: High (H), Medium (M), or Low (L)

CR

Security Context

(User ID)

A Participant User ID belonging to the participant ID having a right to perform Batch Transactions

CR

Participant Transaction ID

21 Alphanumeric characters

CR

Change Reason Code

4 Numbers

CR

Role ID

4 Characters

OBJ

Objection Code

Up to 8 Characters

OBJ

Role

Up to 4 Characters

OBJ

Proposed Date

YYYYMMDD

CR

NMI Checksum

1 Number

CR

NMI

10 Alphanumeric characters

CR

 

Figure 135 Change request XML file

 

Figure 136 Objection XML file

Creating and submitting batch transactions

All Transaction files are created in the same way although the data required differs depending on the type of Transaction you are creating. For an example of a Change Request Transaction, see Change request XML file.

You can include more than one transaction in one XML file providing they belong to the same Transaction Group The transaction group field in an aseXML Message, see B2B Procedures: Technical Delivery Specification.. The message consists of a header, followed by the transactions. For details, see aseXML Guidelines.

To submit Batch files to the Participant File Server:

  1. Create an XML file according to the aseXML specification.

  2. Compress the file in zip format and save it with a .TMP extension, following the MSATS filename standards. For details, see file name format.

  3. FTP the .TMP file to your Participant Inbox adhering to file size limits.

  4. Rename the file from TMP to zip.

  5. MSATS performs validation and sends an ACK file to your Participant Outbox, either accepting or rejecting the file.

    The ACK file has the same name as the zip file except for the extension. For example. if your file is catsm_12345.zip. MSATS names the ACK file catsm_12345.ACK.

  1. When you receive the matching .ACK file in your Participant Outbox, delete your original zip file from your Participant Inbox.

    MSATS then deletes the ACK file from your Participant Outbox.

  1. The Inbox and Outbox are now empty.

    This process (from step 1) is called the MSATS Hokey-Pokey Protocol.

  1. When MSATS completes validation, you receive a response Transaction zip file. For details, see MSATS to participantPage 1.

Editing a batch change request

The process for editing a Change Request using Batch is almost identical to creating a Change Request. A new Change Request Transaction is submitted, which contains the correct information including one additional data element. This is the request ID of the original Change Request in the <InitiatingRequestID> element (see edited change request).

When you submit the second Change Request, MSATS does the following:

  1. Creates a new Change Request with the status of PVAL (pending validation).

  2. Determines, during the second-level validation, that this is an edit to an existing Change Request.

  3. Cancels the existing Change Request (its status changes to CAN).

  4. Creates a further new Change Request that is a ‘merging’ of the two Change Requests that has a status or REQ. (This is the Change Request that proceeds).

  5. Cancels the first Change Request.

Figure 137 edited change request

For Change Requests edited using Batch, MSATS sends two Change Request Response The information returned by an API after a request is made. Responses are usually in JSON or XML format. (CRR) Transactions:

  1. One for the submitted Change Request providing the correct information.

  2. One for the final new Change Request MSATS creates to merge the original Change Request and the new one.

If there was a problem with the first Change Request because it failed the second-level validations and was rejected; only the first Change Request response is received.

Withdrawing a batch change request

To withdraw a Change Request using Batch, you must submit a message containing a change withdrawal Transaction. The only element supplied is the <RequestID> element (see Change request withdrawal).

The Initiating participant must create the Change Request withdrawal and the user ID identified in the <SecurityContext> element must have the right to submit a change withdrawal Transaction by Batch.

For Change Requests withdrawn using Batch, MSATS sends a Change Request response (CRR) indicating if the withdrawal was successful. The CRR is identical to the CRR received when you submitted the Change Request. It does not indicate it is a response to a Change Request withdrawal rather than a response to a new Change Request. You can identify it by initiatingTransactionID, also used in the withdrawal Transaction. The Request ID is the same as the initial Change Request.

Figure 138 Change request withdrawal

Withdrawing a batch objection

The process for withdrawing an Objection using Batch is almost the same as creating an Objection using the Batch Handlers Allows communications between AEMO's systems and participant systems. When communications are processed using the Batch Handlers, they undergo the same validity checks as if they were processed using the web portal.. For a successful withdrawal, the <ObjectionID> generated in the initial Objection is included in the file. A Batch Handler withdrawal is acknowledged by an Objection withdrawal Transaction in your Participant Outbox.

For Objections withdrawn using the Batch Handlers, MSATS sends an Objection Transaction file indicate if the withdrawal was successful. It is identical to the Objection Transaction received when you submitted the Objection. The Transaction does not state it is a response to an Objection withdrawal rather than a response to a new Objection. It contains the initiatingTransactionID from the initial withdrawal Transaction. The Objection ID is the same as the one being withdrawn.

To log an Objection withdrawal:

  1. Create an XML file according to the current aseXML schema format and include the following element:

Element

Description

Example

<ObjectionID>

The ObjectionID from the initial CRR

<ObjectionID>76543210</ObjectionID>

  1. Name the file according to AEMO specifications and compress the file into a zip format.

  2. Access your Participant Inbox and upload your file.

  3. To view the response, access your Participant Outbox.

Withdrawing objection aseXML file is an example of an aseXML file for withdrawing Objections. The <Header> information provided is the same as the standard for a CATS medium Transaction. However, in the Transactions section of the file, there is a CATS Objection withdrawal Transaction.

These fields are:

Figure 139 Withdrawing objection aseXML file

NMI discovery type 1

To create a NMI See Relevant Rules or Procedures Discovery request:

  1. Create an XML file according to the current aseXML schema format. The data required differs depending on the search criteria entered (such as, Address, Meter Serial ID or DPID). To perform a successful NMI Discovery search using Batch, your XML file must contain one of the following criteria:

- Delivery point See Relevant Rules or Procedures identifier

- Meter serial number

- Physical address

  1. Name the file according to AEMO specifications. The filename consists of the Transaction Group, Priority Level, and a Transaction ID that starts with the participant ID. Save files with an XML extension and must be in lower case.

  2. Name the file according to AEMO specifications and compress the file into a zip format.

  3. Access your Participant Inbox and upload your file.

  4. To view the response, access your Participant Outbox.

You can include multiple Transactions in a single Batch file. Requests are processed individually and MSATS provides a single response per Transaction.

NMI discovery type 2 (obtain standing data)

To create a NMI Discovery type 2 (Obtain Standing Data) request:

  1. Create an XML file according to the current aseXML schema format. The NMI and the checksum are required for a type 2 search.

  2. Name the file according to AEMO specifications and compress the file into a zip format.

  3. Access your Participant Inbox and upload your file.

  4. To view the response, access your Participant Outbox.

NMI Discovery type 3 (Obtain Role Data)

To create a NMI Discovery type 3 (Obtain Role Data) request:

  1. Create an XML file according to the current aseXML schema format with a standard NMI Discovery request header.

    The Type, NMI checksum, and Reason fields are mandatory. Enter NMID for the Transaction Group.

  1. Enter ROLE_REQUEST for the Type.

  2. Name the file according to AEMO specifications and compress the file into a zip format.

  3. Access your Participant Inbox and upload your file.

  4. To view the response, access your Participant Outbox.

Notes:

Creating a report request

You can also request CATS and MDM Meter Data Management system includes the Profile Preparation Service, Basic Meter Profiling, and Data Aggregation. reports using Batch. When a report is processed using Batch, it undergoes the same validity checks as a report processed using the web portal.

All reports, whether requested using the web portal or using Batch, are delivered as zip files placed in your Participant Outbox.

To create a report request:

  1. Create an XML file containing the report request according to the aseXML schema format. Each report requires a different set of parameters; the easiest way to identify the parameters for each report is to request it using the web portal and check the output.

  1. Name the file according to AEMO specifications: The filename consists of the Transaction Group (CATS), Priority Level (M), and the Transaction ID (unique ID that includes the participant ID). Files must be saved with an XML extension and are usually in lower case, for example, catsm_ppppppp_1000.xml.

  2. Compress the file into a zip format.

  3. Access your Participant Inbox and upload your file.

  4. To view the response, access your Participant Outbox.

Batch FTP system status

To create an FTP System Status request:

  1. Create an XML file with the report request according to the aseXML schema format. Each report requires different parameters. The easiest way to identify the parameters for each report is to request it using the web portal and check the output.

  2. Name the file according to AEMO specifications: The filename consists of the Transaction Group (CATS), Priority Level (M), and the Transaction ID (unique ID that includes the participant ID). Files must be saved with an XML extension and are usually in lower case, for example, catsm_ppppppp_1000.xml.

  3. Compress the file into a zip format.

  4. Access your Participant Inbox and upload your file.

  5. To view the response, access your Participant Outbox.