Creates a data-driven subscription for a specified item. This method applies to the Report item type.
Assembly: ReportService2010 (in ReportService2010.dll)
public function CreateDataDrivenSubscription( ItemPath : String, ExtensionSettings : ExtensionSettings, DataRetrievalPlan : DataRetrievalPlan, Description : String, EventType : String, MatchData : String, Parameters : ParameterValueOrFieldReference ) : String
- Type: System.String
The fully qualified URL of the item for which to create a data-driven subscription, including the file name and, in SharePoint mode, the extension.
- Type: ReportService2010.ExtensionSettings
An ExtensionSettings object that contains a list of settings that are specific to the delivery extension.
- Type: ReportService2010.DataRetrievalPlan
A DataRetrievalPlan object that provides settings that are required to retrieve data from a delivery query. The DataRetrievalPlan object contains a reference to a DataSetDefinition object and a DataSourceDefinitionOrReference object.
- Type: System.String
A meaningful description that is displayed to users.
- Type: System.String
The type of event that triggers the data-driven subscription. The valid values are TimedSubscription or SnapshotUpdated.
- Type: System.String
The data that is associated with the specified EventType parameter. This parameter is used by an event to match the data-driven subscription with an event that has fired.
Return ValueType: System.String
A String value containing a subscription ID that uniquely identifies the data-driven subscription in the report server database or SharePoint library.
The table below shows header and permissions information on this operation.
SOAP Header Usage
Native Mode Required Permissions
SharePoint Mode Required Permissions
The length of the ItemPath parameter cannot exceed 260 characters; otherwise, a SOAP exception is thrown with the error code rsItemLengthExceeded.
The ItemPath parameter cannot be null or empty or contain the following reserved characters: : ? ; @ & = + $ , \ * > < | . ". You can use the forward slash character (/) to separate items in the full path name of the folder, but you cannot use it at the end of the folder name.
You can use the GetExtensionSettings method to retrieve a list of the required settings for a delivery extension. You must pass values for these required settings in the ExtensionSettings parameter. For information about e-mail delivery settings, see Reporting Services Delivery Extension Settings.
The DataRetrievalPlan parameter takes a DataRetrievalPlan object as its argument. The DataRetrievalPlan object contains a dataset with a delivery query. The CommandType property of the delivery query (QueryDefinition object) is set to Text by default for data-driven subscriptions and does not have to be specified. If you specify a value for the CommandType property, the value must be Text.
The data source provided or referenced in the dataset for the delivery query must have a CredentialRetrieval setting of Store.
Values for delivery extension settings and parameters can be set to either static values or to field references. When a field reference is specified for delivery extension setting or a parameter, the value of the setting or parameter is data driven. The dataset with the delivery query has a set of fields (Field objects) that are mapped to delivery extension settings (ExtensionParameter objects) and report parameter values (ParameterValue objects). All fields referenced in delivery extension settings and report parameter values must correspond to the fields in the dataset. If the delivery query does not return a field that is specified in a delivery extension setting or a parameter value, the report server raises an error when the subscription is processed.
The value of the EventType parameter must correspond to an event that is configured for the report server. The two events that are used to create subscriptions are TimedSubscription and SnapshotUpdated. Use the ListEvents method to return a list of all events configured for the report server.
The value of the MatchData parameter depends on the event type. If the event is a TimedSubscription event, a ScheduleDefinition object is required as the MatchData parameter. You must first serialize the ScheduleDefinition object as XML in order to pass it as a string value and create a subscription based on the schedule. The XML structure might look like the one in the following example:
<ScheduleDefinition> <WeeklyRecurrence> <StartDateTime>2003-02-24T09:00:00-08:00</StartDateTime> <WeeksInterval>1</WeeksInterval> <DaysOfWeek> <Monday>True</Monday> </DaysOfWeek> </WeeklyRecurrence> </ScheduleDefinition>
The value of the StartDateTime element when passed as an XML string should correspond to the date format ISO 8601. This international date and time standard is the extended format CCYY-MM-DDThh:mm:ss+/-Z where "CC" represents the century, "YY" the year, "MM" the month and "DD" the day. The letter "T" is the date and time separator and "hh", "mm", "ss" represent hour, minute and second, respectively. This representation may be immediately followed by a "Z" to indicate Coordinated Universal Time (UTC). To indicate the time zone, represented as the difference between the local time and Coordinated Universal Time, "Z" is preceded by a "+" or "-" sign, followed by the difference from UTC represented as hh:mm.
If the schedule definition for a TimedSubscription is a shared schedule, you must pass the schedule ID of the shared schedule as the MatchData parameter. The schedule ID is passed as a String, for example, "4608ac1b-fc75-4149-9e15-5a8b5781b843". The schedule ID can be obtained by calling the method.
You can use the XmlSerializer class to convert your object class to an XML string automatically. For more information about the XmlSerializer class, see "System.Xml.XmlSerializer Class" in the Microsoft .NET Framework documentation.
If the event is a SnapshotUpdated subscription, the value of MatchData should be a null reference (Nothing in Visual Basic) (or Nothing in Visual Basic).
Using this method sets the LastExecutedSpecified property of the subscription to false, the Status property of the subscription to new subscription, and all properties of the subscription’s Active object to false. The ModifiedBy and ModifiedDate properties of the item are also updated.
To compile this code example, you must reference the Reporting Services WSDL and import certain namespaces. For more information, see Compiling and Running Code Examples. The following code example uses to add a new data-driven subscription to the report server database: