Final. Participants can use this specification to build their APIs.
\nParticipants use this API to submit a csv formatted payload for the initial population of new CATS Standing Data fields. The Blind Update takes the current record and overwrites it leaving the creation and maintenance dates unchanged. A Blind Update does not:
\nSend notifications to participants.
\nCreate new records.
\nFor more details about the Blind Update Tool, see Technical Guide to MSATS.
\nThis documentation explains the standards, rules, context, conventions, parameters, and methods for the API endpoints.
\nAEMO provides this information as a service targeting Registered Participant's:
\nBusiness analysts and technology staff.
\nAPI developers.
\nAn understanding of the following is required:
\nAPI and JSON or YAML fundamentals.
\nMSATS procedures > provision and maintenance of CATS Standing Data.
\nRESTful programming architecture.
\nBefore you can use the Blind Update Tool API you must:
\nHave a Participant ID. If your company is a Registered Participant, it is set up during the registration process.
\nHave a user ID and password with access rights provided by your company's participant administrator. For details, see user rights access below.
\nHave an API gateway and a Certificate.
\nTest your submission in the pre-production environment before submitting to production. AEMO encourages participants to use the pre-production environment to test procedures and train staff.
\nYou can use the following interfaces:
\nAEMO's API Gateway: Submit csv, track status and retrieve submission results using the Blind Update Tool API.
\nMSATS Web Portal: Upload csv files, track status, and retrieve submission results. For details, see Guide to MSATS Web Portal.
\nInterfaces are interchangeable for submitting and retrieving information. For example, you can upload a Payload to MSATS Web Portal and retrieve results using AEMO’s API Gateway.
\nParticipant Roles having a current relationship with the NMI use the following process to upload and view Blind Update Submissions. Once you are registered for APIs, there is no coordination required with AEMO.
The high-level submission process is:
Create a CSV payload with your Blind Update Submissions following the Guide to CSV Data Format Standard.
\nSubmit the CSV payload to AEMO using one of the submission interfaces.
\nAEMO receives and validates the submission for security and syntax (typically not business validations at this stage).
\nAEMO acknowledges the submission with Accept or Reject. Accept or Reject applies to the entire payload.
\nIf AEMO accepts the submission, it applies business validations and processes the updates later.
\nTrack your submission status using the submissionList endpoint or MSATS Web Portal.
\nDownload the results when ready using the downloadFile endpoint or MSATS Web Portal. The results are a mixture of payload successes and failures. The content is a similar CSV format to the submission with some extra columns.
\nThe following submission rules apply:
\nA rejection on submission, results in the entire payload being rejected.
\nIt must adhere to AEMO's CSV Data Format Standard.
\nEach record in the Blind Update Payload must start with one of the following 3 characters:
– C = comment (metadata)
– I = information
– D = data
Must have a C record for its first and last row.
\nIf you are updating multiple columns for a single MSATS record in the same submission payload, there is one csv row per column.
\nCan have any mixture of tables and columns
\nCan have mixed BUT record types.
\nTo be confirmed.
\nThe limit for a single Payload is 100,000 rows.
\nThe first row of the Blind Update Payload is C and must consist of the following 13 comma separated values:
\nI – information row and D – data row record definitions for each BUT submission.
\nThe submission endpoint has the following 2 elements:
\nA request header.
\nA csv Payload (no query parameters or JSON schema).
\nNone
\nThe Blind Update Tool API endpoints are accessible over the internet or MarketNet via AEMO's e-Hub API gateway. For details, see Guide to AEMO's e-Hub APIs.
\nAPI connections use mTLS certificates to secure the transport layer with encrypted communication and
secure interactions between participants’ and AEMO’s systems.
AEMO issues mTLS certificates to participants on request.
\nThe access right participant administrators provide for access to the Blind Update Tool API endpoints are:
\nsubmission: Web Service Submit CSV BUT
\nsubmissionList: Web Service getBlindUpdateRunList
\ndownloadFile: Web Service Get CSV BUT
\nFor details about user rights access, creating new Participant Users and assigning rights, see Guide to User Rights Management (URM).
\nThe Blind Update Tool API is available over the internet on the following base URLs:
\nAPI details, including Swagger/OAS files are available from AEMO’s API Portal:
\nAEMO APIs support HTTP protocol compression controlled by the HTTP request header attributes, allowing compression before sending and responding. The Blind Update API has the following compressed payload:
\nTo control traffic, AEMO implements Throttling on API Endpoint requests. If Participant ID requests exceed the throttling limit, a HTTP 429 or 422 response returns. For more details, see Response codes.
\nEndpoint | Limits |
|---|---|
submission | 100 requests per minute per participantId The participantId is identified from the X-initiatingParticipantID request header parameter Participants systems must manage this Throttling limit because if you submit multiple JSON requests for the same participantId at the same time, AEMO may reject some |
submissionList | 100 requests per minute per participantId |
downloadFile | 100 requests per minute per participantId |
BUT can update NMIs regardless of their Status Code. This means BUT can update Standing Data for active (NMI Status Code = A), not energised (D, G), Extinct (X), or off market NMIs.
\nPass
If the entire submission is valid, the Initiator receives a positive Acknowledgement 200 with the response code and description.
Fail
The entire Submission is rejected with a negative message acknowledgment sent to the Initiator if it:
Fails header validation.
\nFails CSV Payload validation.
\nFails message level validation.
\nHas duplicate update instructions (same field for the same NMI Standing Data record).
\nWhere a D row or field within the row fails validation, MSATS does not update the CATS Standing Data field.
\nThe submission response D record is updated with the validation failure code and description, for example:
\nFor more information, see Validation.
\nAEMO sends a positive message acknowledgment (status=’Accept’) to the initiating party indicating the payload submitted successfully.
\nMessage acknowledgements include the same X-initiatingTransactionID populated to the request header by the gateway on receipt of the BUT Submission.
\nConnection timeout 10 seconds.
\nResponse timeout (including connection timeout) 30 seconds.
\nFor parties having a relationship with the NMI, you can see the modified fields in a C1 or MSATS Snapshot report, retrieved using API, file, or web interface. The reports provide no specific indication the Blind Update Tool altered the data or when.
\nYou can find the updated fields in the C1 report Snapshot report. For details, see Guide to MSATS Reports.
\nThe C1 report may have records where both the Create and Update timestamps fall outside the C1 reporting period. Ensure this does not cause an issue to your C1 processing.
\nHeader and Payload C row must match. String, Required
\n"},{"key":"X-market","value":"NEM","type":"text","description":"NEM, header and payload C row must match. String, Required
\n"},{"key":"Content-Type","value":"text/csv","type":"text","description":"Specifies the posted request data is in text format. If not provided, AEMO gateway assumes text/csv. String, Optional
\n"},{"key":"Accept","value":"text/csv","type":"text","description":"Identifies which content types (expressed as MIME types) the client can understand
\n"},{"key":"Accept-Encoding","value":"gzip, compress, or deflate","type":"text","description":"Optional
\n"},{"key":"Authorisation","value":"Basic Auth","type":"text","description":"The Participant User’s URM username and password\nThe username and password are concatenated with a colon and encoded in Base64 for security. String, Required
\n"}],"body":{"mode":"raw","raw":"C,PREPROD,BLIND_UPDATE_SUBMISSION,EASTERN,NEMMCO,2022/06/28,12:02:07,,,,NEM,ABHI-006\r\nI,BUS,NMI_DATA,1,NMI,FIELD,NEW_VALUE\r\nD,BUS,NMI_DATA,1,4102482266,SHARED_ISOLATION_POINT_FLAG,Y\r\nC,END OF REPORT,4","options":{"raw":{"language":"text"}}},"url":"{{baseUrl}}/NEMRetail/BlindUpdate/v1/submission","auth":{"type":"basic","basic":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"c701a387-bc78-4430-82e4-ab62d33e8579","id":"c701a387-bc78-4430-82e4-ab62d33e8579","name":"Blind Update Tool API Reference","type":"collection"}},"urlObject":{"path":["NEMRetail","BlindUpdate","v1","submission"],"host":["{{baseUrl}}"],"query":[],"variable":[]}},"response":[{"id":"92c11de5-f896-45c3-894b-93b83cc367ee","name":"Submission example","originalRequest":{"method":"POST","header":[],"url":"NEMRetail/BlindUpdateUI/v1/submission"},"status":"OK","code":200,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{ \r\n \"transactionId\": \"12345-abcd-27\",\r\n \"data\": { \r\n\t \"submissionDate\": \"2022-04-07T22:04:05+10:00\",\r\n \"payloadID\": \"BUT-PARTID-010\",\r\n \"payloadResponseID\": \"100000000001244\",\r\n \"status\": \"Accept\"\r\n }\r\n} "},{"id":"53e955cf-075c-4bf7-818f-8a4e70668727","name":"Successful response","originalRequest":{"method":"POST","header":[{"key":"X-initiatingParticipantID","value":"NEMMCO","description":"The ID of the Initiating Participant","type":"text"},{"key":"X-market","value":"NEM","description":"The ID of the Market","type":"text"},{"key":"Content-Type","value":"text/csv","description":"Required request header","type":"text"}],"body":{"mode":"raw","raw":"C,PREPROD,BLIND_UPDATE_SUBMISSION,EASTERN,NEMMCO,2022/06/28,12:02:07,,,,NEM,ABHI-006\r\nI,BUS,NMI_DATA,1,NMI,FIELD,NEW_VALUE\r\nD,BUS,NMI_DATA,1,4102482266,SHARED_ISOLATION_POINT_FLAG,Y\r\nC,END OF REPORT,4"},"url":"{{baseUrl}}/NEMRetail/BlindUpdate/v1/submission"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"C,PREPROD,BLIND_UPDATE_TOOL,NEMMCO,EASTERN,2022/06/29,14:32:51,,,,NEM,,,\r\nI,BUA,SUBMISSION_DATE,PAYLOAD_ID,PAYLOAD_RESPONSE_ID,STATUS\r\nD,BUA,2022/06/28 12:02:07,ABHI-006,100000000000010,Accept\r\nC,END OF REPORT,4"},{"id":"44fbc937-d07f-4282-9363-78e576df875f","name":"Error example - Missing Header - X-initiatingParticipantID","originalRequest":{"method":"POST","header":[{"key":"X-market","value":"NEM","description":"The ID of the Market","type":"text"},{"key":"Content-Type","value":"text/csv","description":"Required request header","type":"text"}],"body":{"mode":"raw","raw":"C,TEST,BLIND_UPDATE_SUBMISSION,NEMMCO,NEMMCO,2022/05/25,11:01:02,,,,NEM,123ABC-456,,\r\nI,BUS,NMI_DATA,1,NMI,FIELD,VALUE\r\nD,BUT,NMI_DATA,1,N123456789,SHARED_ISOLATION_POINT_FLAG,Y\r\nI,BUS,METER_REGISTER,1,NMI,METER_SERIAL,FIELD,VALUE\r\nD,BUT,METER_REGISTER,1,N123456789,123-AZ56,GPS_COORDINATES_LAT,-37.8409350\r\nI,BUS,REGISTER_IDENTIFIER,1,NMI,METER_SERIAL,REGISTER_ID,FIELD,VALUE\r\nD,BUT,REGISTER_IDENTIFIER,1,N123456789,123-AZ56,13,GPS_COORDINATES,ALLDAY\r\nC,END OF REPORT,8,,,,,,,,,,"},"url":"{{baseUrl}}/NEMRetail/BlindUpdate/v1/submission"},"status":"Missing Header","code":400,"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"errors\": [\r\n {\r\n \"code\": \"400\",\r\n \"title\": \"Missing Header\",\r\n \"detail\": \"Header X-initiatingParticipantID was not found in the request. Access denied.\",\r\n \"source\": \"API Gateway\"\r\n }\r\n ]\r\n}"}],"_postman_id":"a316358f-9952-4d6c-890e-ef737c7016b7"},{"name":"submissionList","id":"d062b1e8-7948-4264-9a90-28ff421cb735","request":{"method":"GET","header":[{"key":"X-initiatingParticipantID","value":"{{X-initiatingParticipantID}}","description":"The ID of the Initiating Participant
\n","type":"text"},{"key":"X-market","value":"{{X-market}}","description":"The ID of the Market
\n","type":"text"},{"key":"Accept","value":"application/json","description":"Required request header
\n","type":"text"}],"url":"{{baseUrl}}/NEMRetail/BlindUpdate/v1/submissionList?status=PROCESSED,RUNNING, ERROR, DOWNLOAD&submissionFromDate=Date&submissionToDate=Date&participantMessageId=Id&butRunId=Id","auth":{"type":"basic","basic":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"c701a387-bc78-4430-82e4-ab62d33e8579","id":"c701a387-bc78-4430-82e4-ab62d33e8579","name":"Blind Update Tool API Reference","type":"collection"}},"urlObject":{"path":["NEMRetail","BlindUpdate","v1","submissionList"],"host":["{{baseUrl}}"],"query":[{"description":{"content":"Status
\n","type":"text/plain"},"key":"status","value":"PROCESSED,RUNNING, ERROR, DOWNLOAD"},{"key":"submissionFromDate","value":"Date"},{"key":"submissionToDate","value":"Date"},{"key":"participantMessageId","value":"Id"},{"key":"butRunId","value":"Id"}],"variable":[]}},"response":[{"id":"42e6d637-87a7-4f57-b73b-6393fbabbb88","name":"submissionList","originalRequest":{"method":"GET","header":[{"key":"X-initiatingParticipantID","value":"NEMMCO","description":"The ID of the Initiating Participant","type":"text"},{"key":"X-market","value":"NEM","description":"The ID of the Market","type":"text"},{"key":"Accept","value":"application/json","description":"Required request header","type":"text"}],"url":{"raw":"{{baseUrl}}/NEMRetail/BlindUpdate/v1/submissionList?submissionFromDate=2022-05-23&submissionToDate=2022-05-24","host":["{{baseUrl}}"],"path":["NEMRetail","BlindUpdate","v1","submissionList"],"query":[{"key":"submissionFromDate","value":"2022-05-23"},{"key":"submissionToDate","value":"2022-05-24"},{"key":"status","value":"PROCESSED","description":"Status","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"blindUpdateRuns\": {\r\n \"resultCount\": \"2\",\r\n \"runDetails\": [\r\n {\r\n \"butRunId\": \"100000000000009\",\r\n \"status\": \"PROCESSED\",\r\n \"submissionTimestamp\": \"2022-06-29T14:23:01\",\r\n \"participantId\": \"EASTERN\",\r\n \"partMessageId\": \"ABHI-006\",\r\n \"rowsSubmitted\": \"1\",\r\n \"rowsSuccess\": \"0\"\r\n },\r\n {\r\n \"butRunId\": \"100000000000010\",\r\n \"status\": \"PENDING\",\r\n \"submissionTimestamp\": \"2022-06-29T14:32:51\",\r\n \"participantId\": \"EASTERN\",\r\n \"partMessageId\": \"ABHI-006\",\r\n \"rowsSubmitted\": \"1\",\r\n \"rowsSuccess\": \"0\"\r\n }\r\n ]\r\n }\r\n}"},{"id":"5382df3f-0be5-42c5-8e71-6bd0c8159011","name":"Error example - Missing Header - X-market","originalRequest":{"method":"GET","header":[{"key":"X-initiatingParticipantID","value":"NEMMCO","description":"The ID of the Initiating Participant","type":"text"},{"key":"Accept","value":"application/json","description":"Required request header","type":"text"}],"url":{"raw":"{{baseUrl}}/NEMRetail/BlindUpdate/v1/submissionList?status=PROCESSED","host":["{{baseUrl}}"],"path":["NEMRetail","BlindUpdate","v1","submissionList"],"query":[{"key":"status","value":"PROCESSED","description":"Status"}]}},"status":"Missing Header","code":400,"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"errors\": [\r\n {\r\n \"code\": \"400\",\r\n \"title\": \"Missing Header\",\r\n \"detail\": \"Header X-market was not found in the request. Access denied.\",\r\n \"source\": \"API Gateway\"\r\n }\r\n ]\r\n}"}],"_postman_id":"d062b1e8-7948-4264-9a90-28ff421cb735"},{"name":"submissionList - response","id":"2d24b3ad-9515-4238-bac3-4d0ebcfd80d2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"RESPONSE","header":[],"auth":{"type":"basic","basic":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"c701a387-bc78-4430-82e4-ab62d33e8579","id":"c701a387-bc78-4430-82e4-ab62d33e8579","name":"Blind Update Tool API Reference","type":"collection"}},"urlObject":{"query":[],"variable":[]},"url":""},"response":[],"_postman_id":"2d24b3ad-9515-4238-bac3-4d0ebcfd80d2"},{"name":"downloadFile","id":"88c7aff0-1e3c-4789-85c6-7b9e93eadb40","request":{"method":"GET","header":[{"key":"X-initiatingParticipantID","value":"{{X-initiatingParticipantID}}","type":"text"},{"key":"X-market","value":"{{X-market}}","type":"text"}],"url":"{{baseUrl}}/NEMRetail/BlindUpdate/v1/downloadFile","auth":{"type":"basic","basic":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"c701a387-bc78-4430-82e4-ab62d33e8579","id":"c701a387-bc78-4430-82e4-ab62d33e8579","name":"Blind Update Tool API Reference","type":"collection"}},"urlObject":{"path":["NEMRetail","BlindUpdate","v1","downloadFile"],"host":["{{baseUrl}}"],"query":[],"variable":[]}},"response":[{"id":"b448b4d9-e848-4fd1-84ce-acc209ea514c","name":"downloadFile","originalRequest":{"method":"GET","header":[{"key":"X-initiatingParticipantID","value":"NEMMCO","type":"text"},{"key":"X-market","value":"NEM","type":"text"}],"url":"{{baseUrl}}/NEMRetail/BlindUpdate/v1/downloadFile"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"C,PREPROD,BLIND_UPDATE_RESPONSE,NEMMCO,EASTERN,2022/06/29,14:12:49,,,,NEM,ABHI-006,100000000000007\r\nI,BUR,NMI_DATA,1,NMI,FIELD,NEW_VALUE,STATUS,RESPONSE_CODE,RESPONSE_DESCRIPTION,OLD_VALUE,UPDATED_ROW_ID,BUT_UPDATE_TS\r\nD,BUR,NMI_DATA,1,2002185326,SHARED_ISOLATION_POINT_FLAG,Y,ERROR,14,This field has been updated by a prior BUT run,,,\r\nC,END OF REPORT,4"},{"id":"d2f05337-9386-43c2-a6d9-a447e3d94e30","name":"Error example - Missing Header - X-initiatingParticipantID","originalRequest":{"method":"GET","header":[{"key":"X-market","value":"NEM","type":"text"}],"url":"{{baseUrl}}/NEMRetail/BlindUpdate/v1/downloadFile"},"status":"Missing Header","code":400,"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"errors\": [\r\n {\r\n \"code\": \"400\",\r\n \"title\": \"Missing Header\",\r\n \"detail\": \"Header X-initiatingParticipantID was not found in the request. Access denied.\",\r\n \"source\": \"API Gateway\"\r\n }\r\n ]\r\n}"}],"_postman_id":"88c7aff0-1e3c-4789-85c6-7b9e93eadb40"},{"name":"downloadFile - response","id":"e7dfe588-5131-43ac-b3a9-9ab1049684a5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"RESPONSE","header":[],"url":"DownloadList: C,PREPROD,BLIND_UPDATE_RESPONSE,NEMMCO,EASTERN,2022/06/29,14:12:49,,,,NEM,ABHI-006,100000000000007\nI,BUR,NMI_DATA,1,NMI,FIELD,NEW_VALUE,STATUS,RESPONSE_CODE,RESPONSE_DESCRIPTION,OLD_VALUE,UPDATED_ROW_ID,BUT_UPDATE_TS\nD,BUR,NMI_DATA,1,2002185326,SHARED_ISOLATION_POINT_FLAG,Y,ERROR,14,This field has been updated by a prior BUT run,,,\nC,END OF REPORT,4","auth":{"type":"basic","basic":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"c701a387-bc78-4430-82e4-ab62d33e8579","id":"c701a387-bc78-4430-82e4-ab62d33e8579","name":"Blind Update Tool API Reference","type":"collection"}},"urlObject":{"port":" C,PREPROD,BLIND_UPDATE_RESPONSE,NEMMCO,EASTERN,2022","path":["06","29,14:12:49,,,,NEM,ABHI-006,100000000000007\nI,BUR,NMI_DATA,1,NMI,FIELD,NEW_VALUE,STATUS,RESPONSE_CODE,RESPONSE_DESCRIPTION,OLD_VALUE,UPDATED_ROW_ID,BUT_UPDATE_TS\nD,BUR,NMI_DATA,1,2002185326,SHARED_ISOLATION_POINT_FLAG,Y,ERROR,14,This field has been updated by a prior BUT run,,,\nC,END OF REPORT,4"],"host":["DownloadList"],"query":[],"variable":[]}},"response":[],"_postman_id":"e7dfe588-5131-43ac-b3a9-9ab1049684a5"}],"auth":{"type":"basic","basic":{"basicConfig":[]}},"event":[{"listen":"prerequest","script":{"id":"b4cb3a13-0bfe-43d9-9385-76af0bf82542","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"6c5a67fc-3011-4780-9f78-115be381bab3","type":"text/javascript","exec":[""]}}]}