campaigns

Creates, updates, deletes, gets or lists a campaigns resource.

Overview

Name	campaigns
Type	Resource
Id	aws.iotfleetwise.campaigns

Fields

The following fields are returned by SELECT queries:

get_campaign

Name	Datatype	Description
name	string	The name of the campaign. (pattern: <code>[a-zA-Z\d-_:]+</code>)
arn	string	The Amazon Resource Name (ARN) of the campaign. (pattern: <code>arn:aws:iotfleetwise:[a-z0-9-]+:[0-9]{12}:campaign/[a-zA-Z\d-_:]{1,100}</code>)
collection_scheme	object	Information about the data collection scheme associated with the campaign.
compression	string	Whether to compress signals before transmitting data to Amazon Web Services IoT FleetWise. If OFF is specified, the signals aren't compressed. If it's not specified, SNAPPY is used. (OFF, SNAPPY)
creation_time	string (date-time)	The time the campaign was created in seconds since epoch (January 1, 1970 at midnight UTC time).
data_destination_configs	array	The destination where the campaign sends data. You can send data to an MQTT topic, or store it in Amazon S3 or Amazon Timestream. MQTT is the publish/subscribe messaging protocol used by Amazon Web Services IoT to communicate with your devices. Amazon S3 optimizes the cost of data storage and provides additional mechanisms to use vehicle data, such as data lakes, centralized data storage, data processing pipelines, and analytics. You can use Amazon Timestream to access and analyze time series data, and Timestream to query vehicle data so that you can identify trends and patterns.
data_extra_dimensions	array	A list of vehicle attributes associated with the campaign.
data_partitions	array	The data partitions associated with the signals collected from the vehicle.
description	string	The description of the campaign. (pattern: <code>[^\u0000-\u001F\u007F]+</code>)
diagnostics_mode	string	Option for a vehicle to send diagnostic trouble codes to Amazon Web Services IoT FleetWise. (OFF, SEND_ACTIVE_DTCS)
expiry_time	string (date-time)	The time the campaign expires, in seconds since epoch (January 1, 1970 at midnight UTC time). Vehicle data won't be collected after the campaign expires.
last_modification_time	string (date-time)	The last time the campaign was modified.
post_trigger_collection_duration	integer (int64)	How long (in seconds) to collect raw data after a triggering event initiates the collection.
priority	integer	A number indicating the priority of one campaign over another campaign for a certain vehicle or fleet. A campaign with the lowest value is deployed to vehicles before any other campaigns.
signal_catalog_arn	string	The ARN of a signal catalog.
signals_to_collect	array	Information about a list of signals to collect data on.
signals_to_fetch	array	Information about a list of signals to fetch data from.
spooling_mode	string	Whether to store collected data after a vehicle lost a connection with the cloud. After a connection is re-established, the data is automatically forwarded to Amazon Web Services IoT FleetWise. (OFF, TO_DISK)
start_time	string (date-time)	The time, in milliseconds, to deliver a campaign after it was approved.
status	string	The state of the campaign. The status can be one of: CREATING, WAITING_FOR_APPROVAL, RUNNING, and SUSPENDED. (CREATING, WAITING_FOR_APPROVAL, RUNNING, SUSPENDED)
target_arn	string	The ARN of the vehicle or the fleet targeted by the campaign.

list_campaigns

Name	Datatype	Description
name	string	The name of a campaign. (pattern: <code>[a-zA-Z\d-_:]+</code>)
arn	string	The Amazon Resource Name (ARN) of a campaign. (pattern: <code>arn:aws:iotfleetwise:[a-z0-9-]+:[0-9]{12}:campaign/[a-zA-Z\d-_:]{1,100}</code>)
creation_time	string (date-time)	The time the campaign was created.
description	string	The description of the campaign. (pattern: <code>[^\u0000-\u001F\u007F]+</code>)
last_modification_time	string (date-time)	The last time the campaign was modified.
signal_catalog_arn	string	The ARN of the signal catalog associated with the campaign.
status	string	The state of a campaign. The status can be one of the following: CREATING - Amazon Web Services IoT FleetWise is processing your request to create the campaign. WAITING_FOR_APPROVAL - After a campaign is created, it enters the WAITING_FOR_APPROVAL state. To allow Amazon Web Services IoT FleetWise to deploy the campaign to the target vehicle or fleet, use the API operation to approve the campaign. RUNNING - The campaign is active. SUSPENDED - The campaign is suspended. To resume the campaign, use the API operation. (CREATING, WAITING_FOR_APPROVAL, RUNNING, SUSPENDED)
target_arn	string	The ARN of a vehicle or fleet to which the campaign is deployed.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_campaign	select	region		Retrieves information about a campaign. Access to certain Amazon Web Services IoT FleetWise features is currently gated. For more information, see Amazon Web Services Region and feature availability in the Amazon Web Services IoT FleetWise Developer Guide.
list_campaigns	select	region		Lists information about created campaigns. This API operation uses pagination. Specify the nextToken parameter in the request to return more results.
create_campaign	insert	region, name, signalCatalogArn, targetArn, collectionScheme		Creates an orchestration of data collection rules. The Amazon Web Services IoT FleetWise Edge Agent software running in vehicles uses campaigns to decide how to collect and transfer data to the cloud. You create campaigns in the cloud. After you or your team approve campaigns, Amazon Web Services IoT FleetWise automatically deploys them to vehicles. For more information, see Collect and transfer data with campaigns in the Amazon Web Services IoT FleetWise Developer Guide. Access to certain Amazon Web Services IoT FleetWise features is currently gated. For more information, see Amazon Web Services Region and feature availability in the Amazon Web Services IoT FleetWise Developer Guide.
update_campaign	update	region, name, action		Updates a campaign.
delete_campaign	delete	region		Deletes a data collection campaign. Deleting a campaign suspends all data collection and removes it from any vehicles.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

get_campaign

Retrieves information about a campaign. Access to certain Amazon Web Services IoT FleetWise features is currently gated. For more information, see Amazon Web Services Region and feature availability in the Amazon Web Services IoT FleetWise Developer Guide.

SELECT
name,
arn,
collection_scheme,
compression,
creation_time,
data_destination_configs,
data_extra_dimensions,
data_partitions,
description,
diagnostics_mode,
expiry_time,
last_modification_time,
post_trigger_collection_duration,
priority,
signal_catalog_arn,
signals_to_collect,
signals_to_fetch,
spooling_mode,
start_time,
status,
target_arn
FROM aws.iotfleetwise.campaigns
WHERE region = '{{ region }}' -- required
;

list_campaigns

Lists information about created campaigns. This API operation uses pagination. Specify the nextToken parameter in the request to return more results.

SELECT
name,
arn,
creation_time,
description,
last_modification_time,
signal_catalog_arn,
status,
target_arn
FROM aws.iotfleetwise.campaigns
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_campaign

Creates an orchestration of data collection rules. The Amazon Web Services IoT FleetWise Edge Agent software running in vehicles uses campaigns to decide how to collect and transfer data to the cloud. You create campaigns in the cloud. After you or your team approve campaigns, Amazon Web Services IoT FleetWise automatically deploys them to vehicles. For more information, see Collect and transfer data with campaigns in the Amazon Web Services IoT FleetWise Developer Guide. Access to certain Amazon Web Services IoT FleetWise features is currently gated. For more information, see Amazon Web Services Region and feature availability in the Amazon Web Services IoT FleetWise Developer Guide.

INSERT INTO aws.iotfleetwise.campaigns (
name,
description,
signalCatalogArn,
targetArn,
startTime,
expiryTime,
postTriggerCollectionDuration,
diagnosticsMode,
spoolingMode,
compression,
priority,
signalsToCollect,
collectionScheme,
dataExtraDimensions,
tags,
dataDestinationConfigs,
dataPartitions,
signalsToFetch,
region
)
SELECT 
'{{ name }}' /* required */,
'{{ description }}',
'{{ signalCatalogArn }}' /* required */,
'{{ targetArn }}' /* required */,
'{{ startTime }}',
'{{ expiryTime }}',
{{ postTriggerCollectionDuration }},
'{{ diagnosticsMode }}',
'{{ spoolingMode }}',
'{{ compression }}',
{{ priority }},
'{{ signalsToCollect }}',
'{{ collectionScheme }}' /* required */,
'{{ dataExtraDimensions }}',
'{{ tags }}',
'{{ dataDestinationConfigs }}',
'{{ dataPartitions }}',
'{{ signalsToFetch }}',
'{{ region }}'
RETURNING
name,
arn
;

Manifest

# Description fields are for documentation purposes
- name: campaigns
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the campaigns resource.
  - name: name
    value: "{{ name }}"
    description: |
      The name of the campaign to create.
  - name: description
    value: "{{ description }}"
    description: |
      An optional description of the campaign to help identify its purpose.
  - name: signalCatalogArn
    value: "{{ signalCatalogArn }}"
    description: |
      The Amazon Resource Name (ARN) of the signal catalog to associate with the campaign.
  - name: targetArn
    value: "{{ targetArn }}"
    description: |
      The ARN of the vehicle or fleet to deploy a campaign to.
  - name: startTime
    value: "{{ startTime }}"
    description: |
      The time, in milliseconds, to deliver a campaign after it was approved. If it's not specified, 0 is used. Default: 0
  - name: expiryTime
    value: "{{ expiryTime }}"
    description: |
      The time the campaign expires, in seconds since epoch (January 1, 1970 at midnight UTC time). Vehicle data isn't collected after the campaign expires. Default: 253402214400 (December 31, 9999, 00:00:00 UTC)
  - name: postTriggerCollectionDuration
    value: {{ postTriggerCollectionDuration }}
    description: |
      How long (in milliseconds) to collect raw data after a triggering event initiates the collection. If it's not specified, 0 is used. Default: 0
  - name: diagnosticsMode
    value: "{{ diagnosticsMode }}"
    description: |
      Option for a vehicle to send diagnostic trouble codes to Amazon Web Services IoT FleetWise. If you want to send diagnostic trouble codes, use SEND_ACTIVE_DTCS. If it's not specified, OFF is used. Default: OFF
    valid_values: ['OFF', 'SEND_ACTIVE_DTCS']
  - name: spoolingMode
    value: "{{ spoolingMode }}"
    description: |
      Determines whether to store collected data after a vehicle lost a connection with the cloud. After a connection is re-established, the data is automatically forwarded to Amazon Web Services IoT FleetWise. If you want to store collected data when a vehicle loses connection with the cloud, use TO_DISK. If it's not specified, OFF is used. Default: OFF
    valid_values: ['OFF', 'TO_DISK']
  - name: compression
    value: "{{ compression }}"
    description: |
      Determines whether to compress signals before transmitting data to Amazon Web Services IoT FleetWise. If you don't want to compress the signals, use OFF. If it's not specified, SNAPPY is used. Default: SNAPPY
    valid_values: ['OFF', 'SNAPPY']
  - name: priority
    value: {{ priority }}
    description: |
      A number indicating the priority of one campaign over another campaign for a certain vehicle or fleet. A campaign with the lowest value is deployed to vehicles before any other campaigns. If it's not specified, 0 is used. Default: 0
  - name: signalsToCollect
    description: |
      A list of information about signals to collect. If you upload a signal as a condition in a data partition for a campaign, then those same signals must be included in signalsToCollect.
    value:
      - name: "{{ name }}"
        maxSampleCount: {{ maxSampleCount }}
        minimumSamplingIntervalMs: {{ minimumSamplingIntervalMs }}
        dataPartitionId: "{{ dataPartitionId }}"
  - name: collectionScheme
    description: |
      The data collection scheme associated with the campaign. You can specify a scheme that collects data based on time or an event.
    value:
      timeBasedCollectionScheme:
        periodMs: {{ periodMs }}
      conditionBasedCollectionScheme:
        expression: "{{ expression }}"
        minimumTriggerIntervalMs: {{ minimumTriggerIntervalMs }}
        triggerMode: "{{ triggerMode }}"
        conditionLanguageVersion: {{ conditionLanguageVersion }}
  - name: dataExtraDimensions
    value:
      - "{{ dataExtraDimensions }}"
    description: |
      A list of vehicle attributes to associate with a campaign. Enrich the data with specified vehicle attributes. For example, add make and model to the campaign, and Amazon Web Services IoT FleetWise will associate the data with those attributes as dimensions in Amazon Timestream. You can then query the data against make and model. Default: An empty array
  - name: tags
    description: |
      Metadata that can be used to manage the campaign.
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"
  - name: dataDestinationConfigs
    description: |
      The destination where the campaign sends data. You can send data to an MQTT topic, or store it in Amazon S3 or Amazon Timestream. MQTT is the publish/subscribe messaging protocol used by Amazon Web Services IoT to communicate with your devices. Amazon S3 optimizes the cost of data storage and provides additional mechanisms to use vehicle data, such as data lakes, centralized data storage, data processing pipelines, and analytics. Amazon Web Services IoT FleetWise supports at-least-once file delivery to S3. Your vehicle data is stored on multiple Amazon Web Services IoT FleetWise servers for redundancy and high availability. You can use Amazon Timestream to access and analyze time series data, and Timestream to query vehicle data so that you can identify trends and patterns.
    value:
      - s3Config:
          bucketArn: "{{ bucketArn }}"
          dataFormat: "{{ dataFormat }}"
          storageCompressionFormat: "{{ storageCompressionFormat }}"
          prefix: "{{ prefix }}"
        timestreamConfig:
          timestreamTableArn: "{{ timestreamTableArn }}"
          executionRoleArn: "{{ executionRoleArn }}"
        mqttTopicConfig:
          mqttTopicArn: "{{ mqttTopicArn }}"
          executionRoleArn: "{{ executionRoleArn }}"
  - name: dataPartitions
    description: |
      The data partitions associated with the signals collected from the vehicle.
    value:
      - id: "{{ id }}"
        storageOptions:
          maximumSize:
            unit: "{{ unit }}"
            value: {{ value }}
          storageLocation: "{{ storageLocation }}"
          minimumTimeToLive:
            unit: "{{ unit }}"
            value: {{ value }}
        uploadOptions:
          expression: "{{ expression }}"
          conditionLanguageVersion: {{ conditionLanguageVersion }}
  - name: signalsToFetch
    description: |
      A list of information about signals to fetch.
    value:
      - fullyQualifiedName: "{{ fullyQualifiedName }}"
        signalFetchConfig:
          timeBased:
            executionFrequencyMs: {{ executionFrequencyMs }}
          conditionBased:
            conditionExpression: "{{ conditionExpression }}"
            triggerMode: "{{ triggerMode }}"
        conditionLanguageVersion: {{ conditionLanguageVersion }}
        actions: "{{ actions }}"

UPDATE examples

update_campaign

Updates a campaign.

UPDATE aws.iotfleetwise.campaigns
SET 
name = '{{ name }}',
description = '{{ description }}',
dataExtraDimensions = '{{ dataExtraDimensions }}',
action = '{{ action }}'
WHERE 
region = '{{ region }}' --required
AND name = '{{ name }}' --required
AND action = '{{ action }}' --required
RETURNING
name,
arn,
status;

DELETE examples

delete_campaign

Deletes a data collection campaign. Deleting a campaign suspends all data collection and removes it from any vehicles.

DELETE FROM aws.iotfleetwise.campaigns
WHERE region = '{{ region }}' --required
;