Ara Partner Parameters
- Rindra Rakotondrasoa
- Renaud Vignery
- Alban Peignier
This page presents all the parameters of Ara's partners and their use.
Parameter format
All parameters are strings, but they can be interpreted as integers, arrays, etc...
An integer (int) with an incorrect value will be interpreted as 0.
A boolean (bool) must take the value "true" or "false". An incorrect value will be interpreted as false.
A string is a string of characters.
A string array ([]string) is a succession of strings separated by commas (example : "token1,token2")
A duration is a sequence of potentially signed decimal numbers, each with a suffix like "300ms", "-1.5h" or "2h45m". Valid units are: "ns", "us" (or "µs"), "ms", "s", "m", "h".
List of parameters
Connection parameters
Ara will make requests using OAuth if the 3 parameters remote_authentication.oauth.client_id, remote_authentication.oauth.client_secret et remote_authentication.oauth.token_url are defined. The parameter remote_authentication.oauth.scopes must be added if is is required by the OAuth server.
Paramètres d'un Partenaire d'Échange
Name | Type | Description |
local_credential | string | Token to identify incoming requests, must be unique |
local_credentials | []string | List of tokens to identify incoming requests, each one must be unique. Adds to a possible token defined in local_credential |
remote_credential | string | Token to identify yourself when Ara sends requests |
remote_authentication.oauth.client_id | string | Identifier used to retrieve the Token for exchanges using OAuth |
remote_authentication.oauth.client_secret | string | Secret utilisé pour récupérer le Token lors d'échanges utilisant OAuth |
remote_authentication.oauth.token_url | string | Secret used to retrieve the Token for exchanges using OAuth |
remote_authentication.oauth.scopes | []string | Liste of scopes used to retrieve the Token for exchanges using OAuth |
local_url | srting | Ara address sent in the SIRI Address parameter |
remote_url | string | Address of the remote partner |
notifications.remote_url | string | Address to send subscription notifications to. Without this parameter, remote_url will be used |
subscriptions.remote_url | string | Address to send subscription requests to. Without this parameter, remote_url will be used |
partner.status.maximum_retry | int | Number of times a CheckStatus can be performed with a status of Unknown before actually changing the partner's status to Unknown. |
rate_limit_per_ip | int | Limit the number of requests per minute and per IP address received by Ara for a partner. |
Identifier settings
Name | Type | Description |
remote_objectid_kind | string | Type of identifier used by the partner |
<connector_name>.remote_objectid_kind | string | Type of identifier used by a particular broadcast connector. List of connectors supporting this parameter: gtfs-rt-trip-updates-broadcaster |
<connector_name>.vehicle_remote_objectid_kind | string | Type of identifier used for vehicles by a particular broadcast connector. List of connectors supporting this parameter: gtfs-rt-vehicle-positions-broadcaster siri-vehicle-monitoring-request-broadcaster |
Format parameters
Identifier generators
The generators all use the same syntax: a string in which you can use values of an attribute included in "%{}". Example: "Operator:Stop::%{id}:LOC".
The possible values are: id, type, and uuid.
uuid is usable in any generator and will insert a uuid generated by Ara. For the other values, their use depends on the generator.
Envelope
The envelope allows specifying a SIRI format other than SOAP which is the default format of the SIRI message envelope used by ARA.
Name | Type | Description |
generators.message_identifier | string | Generator used for the SIRI MessageIdentifier attribute. Only supports uuid |
generators.response_message_identifier | string | Generator used for the SIRI ResponseMessageIdentifier attribute. Only supports uuid |
generators.data_frame_identifier | string | Generator used for the SIRI MessageIdentifier attribute. Supports only the id and uuid attributes. The id attribute will contain the modelDate of Ara (the date in the form YYYY-MM-DD) |
generators.reference_identifier | string | Generator used for all references to SIRI objects that are rewritten or that do not have an object of the right type. Only supports type and uuid |
generators.reference_stop_area_identifier | string | Generator used for all references to StopAreas that cannot be found in Ara. Only supports id, and uuid |
generators.subscription_identifier | string | Generator used for subscription identifiers issued by Ara. Only supports uuid |
siri.envelope | string | Specific format of the envelope for SIRI messages other than |
Collection parameters
The "collect.include_XXX" and "collect.exclude_XXX" parameters work as follows:
If all parameters are empty, everything will be collected
If the "collect.use_discovered_stop_areas" parameter is set, we will only collect the stops collected via the StopPointsDiscovery protocol except those defined by "collect.exclude_lines" and "collect.exclude_stop_areas"
Otherwise, we look to see if we can collect the stop and at least one of its lines. If a parameter "collect.include_XXX" is empty, we collect everything that is not excluded
Name | Type | Description |
collect.priority | int | Partner priority for collection. If two partners can collect the same stop, the one with the highest priority will be chosen |
collect.include_lines | []string | List of row identifiers that the partner should collect. Uses the identifier format defined in remote_objectid_kind |
collect.exclude_lines | []string | List of row identifiers that the partner should not collect. Uses the identifier format defined in remote_objectid_kind |
collect.include_stop_areas | []string | List of stop identifiers that the partner should collect. Uses the identifier format defined in remote_objectid_kind |
collect.exclude_stop_areas | []string | List of stop identifiers that the partner should not collect. Uses the identifier format defined in remote_objectid_kind |
collect.use_discovered_stop_areas | bool | The partner will collect the stops discovered through a StopPointsDiscovery request in addition to those possibly defined in the collect.include_XXX parameters |
collect.situations.internal_tags | []string | List of tags that will be set on Situatiosn collected either from GeneralMessage or SituationExchange |
collect.subscriptions.persistent | bool | Allows collection subscriptions not to be deleted if the partner status becomes DOWN or UNKNOWN DEPRECATED: use collect.persistent instead |
collect.persistent | bool | Allows collection subscriptions and requests not to be deleted if the partner status becomes DOWN or UNKNOWN |
collect.filter_general_messages | bool | GeneralMessageRequests will be filtered by lines or stops |
generalMessageRequest.version2.2 | bool | Uses version 2.2 of SIRI GeneralMessageRequests, in request and in subscription (in practice, change a namespace in the XML) |
discovery_interval | duration | Time between two StopPointsDiscovery or LinesDiscovery requests |
collect.gtfs.ttl | duration | Time between two GTFS-RT requests. Minimum of 30 seconds (default value if parameter is not defined) |
subscriptions.maximum_resources | int | Limits the maximum number of resources that can be subscribed to in 1 SIRI subscription. A negative integer or zero counts as no parameter (no limit) |
Broadcast parameters
All broadcast caches (only used for GTFS-RT at the moment) have a minimum of 10 seconds, and a default value of 60 seconds.
Name | Type | Description |
broadcast.subscriptions.persistent | bool | Allows not to delete broadcast subscriptions if the partner status becomes DOWN or UNKNOWN |
broadcast.siri.stop_monitoring.multiple_subscriptions | bool | Allow to send one NotifyStopMonitoring with multiple StopMonitoringDelivery for each subscription |
broadcast.siri.stop_monitoring.maximum_resources_per_delivery | int | Define the total maximum number of MonitoredStopVisit & MonitoredStopVisitCancellation in aStopMonitoringDelivery |
broadcast.recorded_calls.duration | duration | EstimatedTimetable Notification and Response will contain SIRI RecordedCalls for departed Stop Visits between now and the specified duration |
broadcast.rewrite_journey_pattern_ref | bool | The JourneyPatternRef attribute will be rewritten using the reference_identifier generator in the StopMonitoring broadcast |
broadcast.no_dataframeref_rewriting_from | []string | List of origins (partner slug) for which the DestinationRef attributes will not be rewritten in the StopMonitoring broadcast |
broadcast.no_destinationref_rewriting_from | []string | List of origins (partner slug) for which we will not rewrite the DestinationRef attributes in the StopMonitoring or EstimatedTimetable broadcast |
broadcast.prefer_referent_stop_areas | bool | Estimated Timetable deliveries use the Referent Stop Areas instead of Particular ones (when the Referent Stop Area is broadcastable) |
broadcast.situations.internal_tags | []string | Allow to send only situation having the matching tags; valid for GeneralMessage and SituationExchange |
ignore_stop_without_line | bool | Ignore stops without lines when responding to a StopPointsDiscovery request |
broadcast.gzip_gtfs | bool | Zip the answers to the GTFS-RT requests |
broadcast.gtfs.cache_timeout | duration | Time that we keep in cache the answers to the GTFS-RT requests (after Marshaling) |
<connector_name>.cache_timeout | duration | Time that we keep the cache of the connectors that support it : gtfs-rt-trip-updates-broadcaster |