Service API Reference

The servers listen for request from other clients.

class shapeshifter_uftp.service.agr_service.ShapeshifterAgrService(sender_domain, signing_key, key_lookup_function=None, endpoint_lookup_function=None, host: str = '0.0.0.0', port: int = 8080, path='/shapeshifter/api/v3/message')

Service that represents the Aggregator in the UFTP communication.

This service can receive requests from the DSO.

pre_process_d_prognosis_response(message: DPrognosisResponse) → PayloadMessageResponse

FlexOffer messages are used by AGRs to make DSOs an offer for provision of flexibility. A FlexOffer message contains a list of ISPs and, for each ISP, the change in consumption or production offered and the price for the total amount of flexibility offered. FlexOffer messages can be sent once a FlexRequest message has been received but can also be sent unsolicited. Note that multiple FlexOffer messages may be sent based on a single FlexRequest, e.g. to increase the chance that the DSO will order at least part of its available flexibility. The AGR must make sure that it can actually provide the flexibility offered across all of its FlexOffers.

abstract process_d_prognosis_response(message: DPrognosisResponse)

This method is called after the pre_process_flex_offer method is completed. It gives you the chance to perform longer-running operations outside of the request context.

pre_process_flex_request(message: FlexRequest) → PayloadMessageResponse

FlexRequest messages are used by DSOs to request flexibility from AGRs. In addition to one or more ISP elements with Disposition=Requested, indicating the actual need to reduce consumption or production, the message should also include the remaining ISPs for the current period where Disposition=Available.

abstract process_flex_request(message: FlexRequest)

This function is called after the pre_process_flex_request is completed. It gives you the chance to do longer-running computations or operations on this message.

This method should probably end by sending some Flex Offers to the DSO:

with self.dso_client(message.sender_domain) as client:
    response = client.send_flex_offer(FlexOffer(...)
    # Do something with the response here.

pre_process_flex_offer_response(message: FlexOfferResponse) → PayloadMessageResponse

FlexRequest messages are used by DSOs to request flexibility from AGRs. In addition to one or more ISP elements with Disposition=Requested, indicating the actual need to reduce consumption or production, the message should also include the remaining ISPs for the current period where Disposition=Available.

abstract process_flex_offer_response(message: FlexOfferResponse)

This function is called after the pre_process_flex_request is completed. It gives you the chance to do longer-running computations or operations on this message.

This method should probably end by sending some Flex Offers to the DSO:

with self.dso_client(message.sender_domain) as client:
    response = client.send_flex_offer(FlexOffer(...)
    # Do something with the response here.

pre_process_flex_offer_revocation_response(message: FlexOfferRevocationResponse) → PayloadMessageResponse

Upon receiving and processing a FlexOfferRevocation message, the receiving implementation must reply with a FlexOfferRevocationResponse, indicating whether the revocation was handled successfully.

abstract process_flex_offer_revocation_response(message: FlexOfferRevocationResponse)

This method is called after the pre_process_flex_offer_revocation_response method is completed. It gives you the chance to perform longer-running operations outside of the request context. This method is not expected to return anything.

It is advised that this method ends by sending a FlexSettlementResponse to the DSO:

with self.dso_client(message.sender_domain):
    response = client.send_flex_settlement_response(FlexSettlementResponse(...))
    # do something with the response here.

pre_process_flex_order(message: FlexOrder) → PayloadMessageResponse

FlexOrder messages are used by DSOs to purchase flexibility from an AGR based on a previous FlexOffer. A FlexOrder message contains a list of ISPs, with, for each ISP, the change in consumption or production to be realized by the AGR, and the accepted price to be paid by the DSO for this amount of flexibility. This ISP list should be copied from the FlexOffer message without modification: AGR implementations will (and must) reject FlexOrder messages where the ISP list is not exactly the same as offered.

abstract process_flex_order(message: FlexOrder)

This method is called after the pre_process_flex_order is completed. It gives you the cance to perform longer-running operations outside of the request context. This method is not expected to return anything.

pre_process_flex_reservation_update(message: FlexReservationUpdate) → PayloadMessageResponse

For bilateral contracts, FlexReservationUpdate messages are used by DSOs to signal to an AGR which part of the contracted volume is still reserved and which part is not needed and may be used for other purposes. For each ISP, a power value is given which indicates how much power is still reserved. Zero power means that no power is reserved for that ISP and the sign of the power indicates the direction.

abstract process_flex_reservation_update(message: FlexReservationUpdate)

This method is called after the pre_process_flex_reservation_update method is completed. It gives you the chance to perform longer-running operations outside of the request context. This method is not expected to return anything.

pre_process_flex_settlement(message: FlexSettlement) → PayloadMessageResponse

The FlexSettlement message is sent by DSOs on a regular basis (typically monthly) to AGRs, in order to initiate settlement. It includes a list of all FlexOrders placed by the originating party during the settlement period.

abstract process_flex_settlement(message: FlexSettlement)

This method is called after the pre_process_flex_settlement method is completed. It gives you the chance to perform longer-running operations outside of the request context. This method is not expected to return anything.

It is advised that this method ends by sending a FlexSettlementResponse to the DSO:

with self.get_dso_client(message.sender_domain):
    response = client.send_flex_settlement_response(FlexSettlementResponse(...))
    # do something with the response here.

pre_process_metering_response(message: MeteringResponse) → PayloadMessageResponse

Upon receiving and processing a Metering message, the receiving implementation must reply with a MeteringResponse, indicating whether the update was handled successfully.

abstract process_metering_response(message: MeteringResponse)

This method is called after the pre_process_metering_response method is completed. It gives you the chance to perform longer-running operations outside of the request context. This method is not expected to return anything.

It is advised that this method ends by sending a FlexSettlementResponse to the DSO:

with self.get_dso_client(message.sender_domain):
    response = client.send_flex_settlement_response(FlexSettlementResponse(...))
    # do something with the response here.

pre_process_agr_portfolio_query_response(message: AgrPortfolioQueryResponse) → PayloadMessageResponse

The AgrPortfolioQueryResponse is sent by the CRO after you sent a AgrPortfolioQuery. It contains the list of your connections. It is recommended that you do not perform any long-running operations inside this function, but return a PayloadMessageResponse quickly. Longer-running operations (like a database sync) should be done inside the process_agr_portfolio_query_response method.

abstract process_agr_portfolio_query_response(message: AgrPortfolioQueryResponse)

This method is called after the agr_portfolio_query_response method is completed. It gives you the chance to perform longer-running operations outside of the request context.

If the list of connections does not match what you expected it to be, you can send an AgrPortfolioUpdate message at the end of this method:

with self.get_dso_client(message.sender_domain) as client:
    response = client.send_portfolio_update(AgrPortfolioUpdate(...))
    # Do something with the response here

pre_process_agr_portfolio_update_response(message: AgrPortfolioUpdateResponse)

The AgrPortfolioUptadeResponse is sent by the CRO after you sent a AgrPortfolioUpdate. It is merely a status updateIt is recommended that you do not perform any long-running operations inside this function, but return a PayloadMessageResponse quickly. Longer-running operations (like a database sync) should be done inside the process_agr_portfolio_query_response method.

abstract process_agr_portfolio_update_response(message: AgrPortfolioUpdateResponse)

This method is called after the agr_portfolio_update_response method is completed. It gives you the chance to perform longer-running operations outside of the request context.

cro_client(recipient_domain) → ShapeshifterAgrCroClient

Retrieve a client object for sending messages to the CRO.

dso_client(recipient_domain) → ShapeshifterAgrDsoClient

Retrieve a client object for sending messages to the DSO.

run()

Start the web server that hosts the FastAPI application. Other participants can now send messages to us.

run_in_thread()

Run the service in a background thread.

stop()

Stop the service if it was running in a separate thread.

class shapeshifter_uftp.service.dso_service.ShapeshifterDsoService(sender_domain, signing_key, key_lookup_function=None, endpoint_lookup_function=None, host: str = '0.0.0.0', port: int = 8080, path='/shapeshifter/api/v3/message')

Service that represents the Distribution System Operator in the UFTP communication.

It can receive requests from the Aggregator.

You should subclass this class and implement your own message handling methods.

pre_process_d_prognosis(message: DPrognosis) → PayloadMessageResponse

D-Prognosis messages are used to communicate D-prognoses between AGRs and DSOs. D-Prognosis messages always contain data for all ISPs for the period they apply to, even if a prognosis is sent after the start of the period, when one or more ISPs are already in the operate or settlement phase. Receiving implementations should ignore the information supplied for those ISPs.

abstract process_d_prognosis(message: DPrognosis)

This method is called after the pre_process_d_prognosis method is completed. It gives you the chance to perform longer-running operations outside of the request context.

pre_process_flex_request_response(message: FlexRequestResponse) → PayloadMessageResponse

FlexOffer messages are used by AGRs to make DSOs an offer for provision of flexibility. A FlexOffer message contains a list of ISPs and, for each ISP, the change in consumption or production offered and the price for the total amount of flexibility offered. FlexOffer messages can be sent once a FlexRequest message has been received but can also be sent unsolicited. Note that multiple FlexOffer messages may be sent based on a single FlexRequest, e.g. to increase the chance that the DSO will order at least part of its available flexibility. The AGR must make sure that it can actually provide the flexibility offered across all of its FlexOffers.

abstract process_flex_request_response(message: FlexRequestResponse)

This method is called after the pre_process_flex_offer method is completed. It gives you the chance to perform longer-running operations outside of the request context.

pre_process_flex_offer(message: FlexOffer) → PayloadMessageResponse

FlexOffer messages are used by AGRs to make DSOs an offer for provision of flexibility. A FlexOffer message contains a list of ISPs and, for each ISP, the change in consumption or production offered and the price for the total amount of flexibility offered. FlexOffer messages can be sent once a FlexRequest message has been received but can also be sent unsolicited. Note that multiple FlexOffer messages may be sent based on a single FlexRequest, e.g. to increase the chance that the DSO will order at least part of its available flexibility. The AGR must make sure that it can actually provide the flexibility offered across all of its FlexOffers.

abstract process_flex_offer(message: FlexOffer)

This method is called after the pre_process_flex_offer method is completed. It gives you the chance to perform longer-running operations outside of the request context.

pre_process_flex_order_response(message: FlexOrderResponse) → PayloadMessageResponse

Upon receiving and processing a FlexOrder message, the receiving implementation must reply with a FlexOrderResponse, indicating whether the update was handled successfully.

abstract process_flex_order_response(message: FlexOrderResponse)

This method is called after the pre_process_flex_order_response method is completed. It gives you the chance to perform longer-running operations outside of the request context.

pre_process_flex_offer_revocation(message: FlexOfferRevocation) → PayloadMessageResponse

The FlexOfferRevocation message is used by the AGR to revoke a FlexOffer previously sent to a DSO. It voids the FlexOffer, even if its validity time has not yet expired. Revocation is not allowed for FlexOffers that already have associated accepted FlexOrders.

abstract process_flex_offer_revocation(message: FlexOfferRevocation)

This method runs separately from the pre_process_flex_offer_revocation function. It gives you the chance to perform longer-running operations outside of the request context.

pre_process_flex_reservation_update_response(message: FlexReservationUpdateResponse) → PayloadMessageResponse

The FlexOfferRevocation message is used by the AGR to revoke a FlexOffer previously sent to a DSO. It voids the FlexOffer, even if its validity time has not yet expired. Revocation is not allowed for FlexOffers that already have associated accepted FlexOrders.

abstract process_flex_reservation_update_response(message: FlexReservationUpdateResponse)

This method runs separately from the pre_process_flex_offer_revocation function. It gives you the chance to perform longer-running operations outside of the request context.

pre_process_flex_settlement_response(message: FlexSettlementResponse) → PayloadMessageResponse

Upon receiving and processing a FlexSettlement message, the AGR must reply with a FlexSettlementResponse, indicating whether the initial message was handled successfully. When a FlexSettlement message is rejected, the DSO should consider all FlexOrderSettlement elements of that message related to potential dispute.

abstract process_flex_settlement_response(message: FlexSettlementResponse)

This method runs separately from the pre_process_flex_settlement_response function. It gives you the chance to perform longer-running operations outside of the request context.

pre_process_dso_portfolio_query_response(message: DsoPortfolioQueryResponse) → PayloadMessageResponse

Upon receiving and processing a DSOPortfolioQuery message, the receiving implementation must reply with a DSOPortfolioQueryResponse, indicating whether the query executed successfully, and if it did, including the query results. Most queries will return zero or more congestion points

abstract process_dso_portfolio_query_response(message: DsoPortfolioQueryResponse)

This method runs after the pre_process_dso_portfolio_query_response has finised.

pre_process_dso_portfolio_update_response(message: DsoPortfolioUpdateResponse) → PayloadMessageResponse

Upon receiving and processing a DSOPortfolioUpdate message, the receiving implementation must reply with a DSOPortfolioUpdateResponse, indicating whether the update was handled successfully.

abstract process_dso_portfolio_update_response(message: DsoPortfolioUpdateResponse)

This method runs after the pre_process_portfolio_update_response method has finished.

pre_process_metering(message: Metering) → PayloadMessageResponse

The Metering message is an optional message. The DSO will specify whether metering messages are required for a given program. If metering messages are used then the AGR must send metering messages, with one message sent per connection point per day. The metering messages must all be sent before the settlement can be performed. It is recommend to send the metering messages daily, once the metering data has been collected for the day.

abstract process_metering(message: Metering)

This method runs after the pre_process_metering method has finished.

agr_client(recipient_domain) → ShapeshifterDsoAgrClient

Retrieve a client object for sending messages to the AGR.

cro_client(recipient_domain) → ShapeshifterDsoCroClient

Retrieve a client object for sending messages to the CRO.

run()

Start the web server that hosts the FastAPI application. Other participants can now send messages to us.

run_in_thread()

Run the service in a background thread.

stop()

Stop the service if it was running in a separate thread.

class shapeshifter_uftp.service.cro_service.ShapeshifterCroService(sender_domain, signing_key, key_lookup_function=None, endpoint_lookup_function=None, host: str = '0.0.0.0', port: int = 8080, path='/shapeshifter/api/v3/message')

Service that represent the Common Reference Operator in the UFTP communication.

It can receive requests from the Aggregator and from the DSO.

pre_process_agr_portfolio_query(message: AgrPortfolioQuery) → PayloadMessageResponse

The AGRPortfolioQuery is used by the AGR to retrieve additional information on the connections.

abstract process_agr_portfolio_query(message: AgrPortfolioQuery)

This method is called after the agr_portfolio_query method is completed. It gives you the chance to perform longer-running operations outside of the request context.

pre_process_agr_portfolio_update(message: AgrPortfolioUpdate) → PayloadMessageResponse

The AGRPortfolioUpdate is used by the AGR to indicate on which Connections it represents prosumers.

abstract process_agr_portfolio_update(message: AgrPortfolioUpdate)

This method is called after the agr_portfolio_update method is completed. It gives you the chance to perform longer-running operations outside of the request context.

pre_process_dso_portfolio_query(message: DsoPortfolioQuery) → PayloadMessageResponse

DSOPortfolioQuery is used by DSOs to discover which AGRs represent connections on its registered congestion point(s).

abstract process_dso_portfolio_query(message: DsoPortfolioQuery)

This method is called after the dso_portfolio_query method is completed. It gives you the chance to perform longer-running operations outside of the request context.

You should end this method by sending a DsoPortfolioQueryResponse back to the DSO:

with self.get_dso_client(message.sender_domain) as client:
    client.send_portfolio_query_response

pre_process_dso_portfolio_update(message: DsoPortfolioUpdate) → PayloadMessageResponse

The DSOPortfolioUpdate is used by the DSO to indicate on which congestion points it wants to engage in flexibility trading.

abstract process_dso_portfolio_update(message: DsoPortfolioUpdate)

This method is called after the dso_portfolio_update method is completed. It gives you the chance to perform longer-running operations outside of the request context.

agr_client(recipient_domain) → ShapeshifterCroAgrClient

Retrieve a client object for sending messages to the AGR.

dso_client(recipient_domain) → ShapeshifterCroDsoClient

Retrieve a client object for sending messages to the DSO.

run()

Start the web server that hosts the FastAPI application. Other participants can now send messages to us.

run_in_thread()

Run the service in a background thread.

stop()

Stop the service if it was running in a separate thread.