Apron Services XML Properties

APRON SERVICES XML PROPERTIES

IMPORTANT! This article is a stub that has been created in preparation for future updates and as such contains no meaningful information on this subject.

The <apron_service_name>.xml file is used to define a single service that will be available to the ApronControl at an airport. This file defines the behaviours for the service based on a simple state machine concept. Note that this file combines the elements shown here with elements that come from Navigation Services and Flights And Missions as well.

When using full apron services for a facility, this file is only used to control the way the service is spawned and a few other important parts of controlling the flow of services in and around a context request, but it does not control the service itself. Each service spawned should have it's own Navigation Services XML Properties that control the flow of actions of the service, and that send a "finished" event to the Apron Service context controller so that it can either tell the Apron Control Unit that the service is finished, or move on to the next part of the service context request. However, the exception to this is when the file being written is a fallback file, in which case all flow logic for the service should go here, including that which would normally be a unique navigation service. For more information, please see here:

Fallback Services

The file for each apron service is written using XML, and it can easily be created and edited using any text editor. The general format for the file is shown in the schema template below:

<SimBase.Document Type="MissionFile" version="1.0">
    <Descr>Apron Controler - Template Service</Descr>
    <WorldBase.Flight>
        <!-- TRIGGER THE INITIAL STATE -->
        <SimMission.TimerTrigger InstanceId="{XXX-XXX-XXX-XXX-XXX}">
            <Descr>Launch initial state</Descr>
            <Activated>True</Activated>
            <OneShot>True</OneShot>
            <OnScreenTimer>True</OnScreenTimer>
            <StartTime>0.000</StartTime>
            <StopTime>0.000</StopTime>
            <Actions>
                <ObjectReference id="INITIAL STATE" InstanceId="{Initial state GUID}"/>        
            </Actions>
        </SimMission.TimerTrigger>
    
        <!-- INITIAL STATE -->
        <SimMission.StateAction InstanceId="{Initial state GUID}">
            <Descr>StateAction:TemplateInit</Descr>
            <StateName>TemplateInit</StateName>
            <OnFirstFrame>
                <FromStateCase>
                    <Actions>
                        <ObjectReference id="Start actions" InstanceId=""/>
                    </Actions>
                </FromStateCase>
            </OnFirstFrame>
        </SimMission.StateAction>
        
        <!-- FINAL STATE -->
        <SimMission.StateAction InstanceId="{Final state GUID}">
            <Descr>StateAction:FINISH</Descr>
            <StateName>FINISH</StateName>
            <OnFirstFrame>
                <FromStateCase>
                    <Actions>
                        <ObjectReference id="Stop mission finished event trigger" InstanceId="{Stop Mission GUID}"/>
                        <ObjectReference id="Notify ApC mission context flow is finished" InstanceId="{Notification GUID}"/>
                    </Actions>
                </FromStateCase>
            </OnFirstFrame>
        </SimMission.StateAction>
        
        <SimMission.ObjectActivationAction InstanceId="{Stop Mission GUID}">
            <Descr>Stop mission finished event trigger</Descr>
            <NewObjectState>False</NewObjectState>
            <ObjectReferenceList>
                <ObjectReference InstanceId="{Finished Trigger GUID}" id="Mission finished event trigger"/>
            </ObjectReferenceList>
        </SimMission.ObjectActivationAction>
        
        <SimMission.FlowEventTrigger InstanceId="{Finished Trigger GUID}">
            <Descr>On mission finish</Descr>
            <Activated>True</Activated>
            <OneShot>True</OneShot>
            <SimMission.FlowEvents>
                <FlowEvent id="CHAIN_MISSION_END"/>
            </SimMission.FlowEvents>
            <Actions>
                <ObjectReference id="Launch final state" InstanceId="{Final state GUID}"/>
            </Actions>
        </SimMission.FlowEventTrigger>
        
        <!-- ApronControl Actions Here-->
        <ApronControl.ApronContextReference id="Context" InstanceId="{Apron Context GUID}" ApronReferenceType="Context" />
        <ApronControl.ApronContextReference id="Aircraft" InstanceId="{Aircraft Object GUID}" ApronReferenceType="Aircraft" />
        <ApronControl.ApronControlAssignNavigationGraphAction InstanceId="{Graph Action GUID}">
            <Descr>Assign navigation graphs</Descr>
            <NavigationGraph>
                <NavigationGraphName>Gate</NavigationGraphName>
            </NavigationGraph>
            <NavigationGraph>
                <NavigationGraphName>GateToAircraftStand</NavigationGraphName>
            </NavigationGraph>
            <ObjectReference id="ApronContextReference:Aircraft" InstanceId="{Aircraft GUID}"/>
            <Context>
                <ObjectReference id="ApronContextReference:Context" InstanceId="{Apron Context GUID}"/>
            </Context>
            <CabinName>CABIN_SERVICE_NAME</CabinName>
            <Path>
                <TagToLink>LINK_TAG</TagToLink>
            </Path>
        </ApronControl.ApronControlAssignNavigationGraphAction>
        <ApronControl.ApronControlFinishedAction InstanceId="{Notification GUID}">
            <Descr>Tell the mission context that the flow is finished</Descr>
            <ObjectReference id="ApronContextReference:Context" InstanceId="{Apron Context GUID}"/>
        </ApronControl.ApronControlFinishedAction>
        <!-- Further ApronControl Actions -->
        
    </WorldBase.Flight>
</SimBase.Document>

<ApronControl.ApronContextReference />

This self-closing element permits you to get a reference to a SimObject from the current Apron Control request context, such as a that of a vehicle or the aircraft that requested the context. For example:

<ApronControl.ApronContextReference id="Aircraft" InstanceId="{5C4F5800-E9BC-4445-9EEF-1571458FDF9D}" ApronReferenceType="Aircraft" />

The element may also be used to get a reference to the context itself for use by a tag in its code, or by a service.

This sub-element has the following parameters:

Attribute Description Type Required

id The unique identifier of the object element/apron control reference. This may be arbitray for some context types, or it may have to be a specific string. Please see the ApronReferenceType attribute, explained below. String No

InstanceId The unique ID for apron context reference, as a GUID enclosed in {}, to be used elsewhere. You can find more information on GUID's here: GUIDs String Yes

Attribute	Description	Type	Required
`id`	The unique identifier of the object element/apron control reference. This may be arbitray for some context types, or it may have to be a specific string. Please see the `ApronReferenceType` attribute, explained below.	String	No
`InstanceId`	The unique ID for apron context reference, as a GUID enclosed in {}, to be used elsewhere. You can find more information on GUID's here: GUIDs	String	Yes
`ApronReferenceType`	This is where you select the reference type, which can be any of the following: ApronControl: The apron control unit that spawned the context. Aircraft: The aircraft that requested the context. If you use this, then the `id` attribute should be "Aircraft" Context: The context itself. Jetway: This is only used if the current parking has a Jetway. If you use this, then the `id` attribute should be "Jetway" Mission: This will look into the mission context for items added with the `<SimMission.ApronControlRegisterToContextAction>` element. Vehicle: This is used for Apron Control vehicles (buses, ramps, etc…). With this type, the precise type of vehicle is indicated by the `id` field, and must match the Name defined in the ApronControlServices.xml.	String	Yes

ApronReferenceType

This is where you select the reference type, which can be any of the following:

ApronControl: The apron control unit that spawned the context.
Aircraft: The aircraft that requested the context. If you use this, then the id attribute should be "Aircraft"
Context: The context itself.
Jetway: This is only used if the current parking has a Jetway. If you use this, then the id attribute should be "Jetway"
Mission: This will look into the mission context for items added with the <SimMission.ApronControlRegisterToContextAction> element.
Vehicle: This is used for Apron Control vehicles (buses, ramps, etc…). With this type, the precise type of vehicle is indicated by the id field, and must match the Name defined in the ApronControlServices.xml.

String

Yes

<ApronControl.ApronControlAssignServiceAction>

This element is used to assign a vehicle from the Apron Control reserve to the current context, which is provided through the use of an "ApronContextReference:Context" object reference, for example:

<ApronControl.ApronControlAssignServiceAction InstanceId="{C2F12763-A665-4141-969B-EB13522BAEDF}">
    <Descr>Assign a bus to the mission context</Descr>
    <ApronControlServiceType>BUS</ApronControlServiceType>
    <ObjectReference id="ApronContextReference:Context" InstanceId="{70A994D6-EC3A-4DAE-A9D9-B78C1E5F3B55}"/>
</ApronControl.ApronControlAssignServiceAction>

This element requires the following sub-elements:

The element also has the following attribute:

Attribute	Description	Type	Required
`InstanceId`	The unique ID for reference to the element, as a GUID enclosed in {}, to be used elsewhere. You can find more information on GUID's here: GUIDs	String	Yes

<ApronControl.ApronControlFreeServiceAction>

This element is used to revert the call to a vehicle and remove it from the given context (use "ApronContextReference:Context" for the object ID), returning it to the Apron Control reserve, so the vehicle can be assigned to another service again. For example:

<ApronControlFreeServiceAction InstanceId="{338B4D45-9D23-4DE3-8FDC-1042D0A6889B}">
    <Descr>Free the bus so it can go on another mission</Descr>
    <ApronControlServiceType>RAMP</ApronControlServiceType>
    <ObjectReference id="ApronContextReference:Context" InstanceId="{70A994D6-EC3A-4DAE-A9D9-B78C1E5F3B55}"/>
</ApronControlFreeServiceAction>

Note that you should ensure that the vehicle is returning to its sleep position before freeing it.

This element requires the following sub-elements:

The element also has the following attribute:

Attribute	Description	Type	Required
`InstanceId`	The unique ID for reference to the element, as a GUID enclosed in {}, to be used elsewhere. You can find more information on GUID's here: GUIDs	String	Yes

<ApronControl.ApronControlAssignNavigationGraphAction>

This element is used to add navigation graphs to the given Apron Control context and the aircraft associated with the context. You may supply the name of one or more navigation graph files for use, as long as they have been added to the navigation_graph folder of the airport being worked on. The path would be something like:

[Airport Project]\PackageSources\data\navigation_graph\

When this action element is called, it first finds a Navigation Service with the given <CabinName> by looking into all the services associated with the aircraft being referenced in the <ObjectReference /> (the id attribute should be "ApronContextReference:Aircraft"), and it also retrieves the navigation graph associated with this navigation service. The next thing that happens is that the action retrieves the navigation graphs defined using the <NavigationGraph> element and links them with the aircraft navigation service and the given <Context>.

For example:

<ApronControl.ApronControlAssignNavigationGraphAction InstanceId="{82044056-EBA5-4AE1-8607-32209F976DC9}">
    <Descr>Assign payload graphs of the gate and the one from gate to parking to the passenger cabin service</Descr>
    <NavigationGraph>
        <NavigationGraphName>Gate</NavigationGraphName>
    </NavigationGraph>
    <NavigationGraph>
        <NavigationGraphName>GateToAircraftStand</NavigationGraphName>
    </NavigationGraph>
    <ObjectReference id="ApronContextReference:Aircraft" InstanceId="{4AEBA072-63C6-461E-A6F9-2C7C65B3FEED}"/>
    <Context>
        <ObjectReference id="ApronContextReference:Context" InstanceId="{70A994D6-EC3A-4DAE-A9D9-B78C1E5F3B55}"/>
    </Context>
    <CabinName>PassengerBoardingService</CabinName>
    <Path>
        <TagToLink>GATE_TO_STAND</TagToLink>
    </Path>
</ApronControl.ApronControlAssignNavigationGraphAction>

This element requires the following sub-elements:

The element also has the following attribute:

Attribute	Description	Type	Required
`InstanceId`	The unique ID for reference to the element, as a GUID enclosed in {}, to be used elsewhere. You can find more information on GUID's here: GUIDs	String	Yes

<NavigationGraph>

This sub-element of <ApronControl.ApronControlAssignNavigationGraphAction> is a container element for <NavigationGraphName> and has no attributes.

<NavigationGraphName>

This sub-element of <NavigationGraph> has no attributes and is used to define the part of the name to check for to find the appropriate navigation graph file to be used by the action. This element can only have the following strings:

GateToAircraftStand: the navigation graph file must contain the sub-string "_gateToStand_" and link a departure gate with a taxiway parking stand. Note that the file name must follow the format given below so that the context can find it:

navigation_graph_[ICAO]_gateToStand_[ParkingName]_[ParkingNumber]_[ParkingSuffix]
Gate: the navigation graph file must contain the sub-string "_gate_" and link a departure gate to a jetway or a passenger ramp at a taxiway parking stand. Note that the file name must follow the format given below so that the context can find it:

navigation_graph_[ICAO]_gate_[ParkingName]

<CabinName>

This sub-element of <ApronControl.ApronControlAssignNavigationGraphAction> has no attributes and is used to define the name of the Navigation Service to check the aircraft for.

<Context>

This sub-element of <ApronControl.ApronControlAssignNavigationGraphAction> has no attributes and is used to specify the apron control context that the action is to be performed on. It requires the following sub-element to be used to give the context (the id attribute should be "ApronContextReference:Context"):

<ObjectReference />

<Path>

This sub-element of <ApronControl.ApronControlAssignNavigationGraphAction> has no attributes and is a container element for one or more <TagToLink> elements.

<TagToLink>

This sub-element of <Path> is used to define the tag of the nodes in the apron service navigation graphs to connect with an edge. The tag name can be a general value, as the simulation will generate a complete and unique tag name from the rest of the data derived from the position of the parking space. The final computed tag will be:

[Tag Name]_[ParkingName]_[ParkingNumber]_[ParkingSuffix]

<ApronControl.ApronControlAssignDestinationAction>

This element is used to give the currently active Navigation Service a destination target which will be used during its next call to <TaxiAIMoveToDestination />. The action requires an <ObjectReference /> (the id attribute should be "ApronContextReference:Context"), which is the apron control context that was defined with <ApronControl.ApronContextReference />. For example:

<ApronControl.ApronControlAssignDestinationAction InstanceId="{C264BF46-299D-4836-9197-D58F69140777}">
    <Descr>Give the bus taxi ai the destination of the gate parking</Descr>
    <ApronControlServiceType>BUS</ApronControlServiceType>
    <DestinationType>Gate</DestinationType>
    <ObjectReference id="ApronContextReference:Context" InstanceId="{70A994D6-EC3A-4DAE-A9D9-B78C1E5F3B55}"/>
</ApronControl.ApronControlAssignDestinationAction>

This element requires the following sub-elements:

The element also has the following attribute:

Attribute	Description	Type	Required
`InstanceId`	The unique ID for reference to the element, as a GUID enclosed in {}, to be used elsewhere. You can find more information on GUID's here: GUIDs	String	Yes

<DestinationType>

This is a sub-element of <ApronControl.ApronControlAssignDestinationAction> and it has no attributes. It is used to assign the type of destination for a navigation service that has been called as part of an apron control service. The possible destinations are as follows:

Gate: The destination is a gate where passengers can be picked up. Used by bus services only.
Aircraft: The destination is next to the aircraft parking spot.
Parking: The destination is the taxiway services stand (where vehicles spawn, or remain when at rest with no current task).

<ApronControl.ApronControlFinishedAction>

This element is used to tell the Apron Control unit that the given context flow has finished and that the context can be destroyed. For example:

<ApronControl.ApronControlFinishedAction InstanceId="{BC2AC51C-2B1F-480F-96A1-0919A14DD042}">
    <Descr>Tell the mission context that the flow is finished</Descr>
    <ObjectReference id="ApronContextReference:Context" InstanceId="{70A994D6-EC3A-4DAE-A9D9-B78C1E5F3B55}"/>
</ApronControl.ApronControlFinishedAction>

This element requires the following sub-elements:

<ObjectReference />

The element also has the following attribute:

Attribute	Description	Type	Required
`InstanceId`	The unique ID for reference to the element, as a GUID enclosed in {}, to be used elsewhere. You can find more information on GUID's here: GUIDs	String	Yes

<ApronControlServiceType>

This element has no attributes and is used by the following parent elements:

The contents of this element are used to define a specific type of service that is being targeted by the apron service context. It can be any of the following:

None
ApronControl
Vehicle
Aircraft
Jetway
Context
Mission