Bulk Data – Feature Import Specification

Article Contents

Summary

This article provides guidelines for using the Bulk Data application to import files to add or modify features on an account or service. This includes products, packages, discounts, contracts, dynamic charges and pricing plans.

Adding Features:

This import can add features to an account or service by creating an order. When successfully processed, each line in the import file will result in an order line in the IDI platform. The orders will then need to be processed for the features to be added to the specified accounts or services.

When adding a feature, an order type must be specified for each record in the import file. The orders created from this import will follow the same order processing logic as orders manually created for the order type. Note that this can result in provisioning. If provisioning is not desired, an order type that is not setup to start a task plan should be used.

Modifying Features:

Capability to use this import to modify features on an account or service was added in the IDI platform version 20.2. This import supports modifying the following properties on a feature: start date, end date, billing status, quantity, charge, cost, wholesale cost, and product attributes.

No order is created when modifying features. The feature is updated directly on the account or service.

Note: Adding and modifying features can be handled in the same file or be done in separate files, depending on your preference and what works best for a particular application.

Links:

PDF Version

Example File

Account Level Features

Action = Create

A feature will be added at the account level when the ServiceID, ServiceNumber and ServiceTypeSKU fields are blank on the import file record.

Action = Modify

When Action = Modify, the FeatureID (NonUsgSvcID) must be provided, and the Account Number, Service ID, Service Number and Service Type SKU are not required or evaluated.

Service Level Features

Action = Create

A feature will be added to a service when either the ServiceID (which is UsgSvcID) OR the ServiceNumber and ServiceType SKU are provided.

Features can only be added to active services. If the service information provided cannot be associated to an active service, an error will be generated.

Note: If all three are provided (ServiceID, ServiceNumber, ServiceType SKU) with Action = Create, the ServiceID will be used to identify the service. No additional validation is done to verify the service number and service type correctly correspond to the ServiceID provided.

Action = Modify

Service level features can be modified using Action = Modify and providing the FeatureID (which is the NonUsgSvcID). The Account Number, Service ID, Service Number and Service Type SKU are not required to modify a feature. If they are provided, they are not evaluated.

An action of Modify without providing the FeatureID will result in an error.

Order Grouping

When adding features (Action = Create), the feature import will create a unique order for sequential file lines for the same account number, order type, and starting block ID (when specified). The default behavior can be overridden using the StartNewOrder field.

A value of True in the StartNewOrder field will force a new order to be started with the current line.

Errors

Each line will be individually evaluated for errors. Error messages will be written to an error file, which can be downloaded from the file details page in the Bulk Data web module.

Note: For multi-line orders, if any line has an error, all lines for the order will result in error. For lines that are only in error due to being grouped with an order line that is in error, the following error message will be logged: This item errored because at least one other item in the same order errored.

Attributes

When adding features (Action = Create), attribute values can be provided for both the order type and the product. The header record must list a field for each unique attribute property name that is being assigned a value in the file.

When modifying a feature (Action = Modify), only the product attributes apply.

In the file header record, the attribute fields must be pre-fixed as follows:

Order Type Attributes: ATTRORD_<attribute property name>
Product Attributes: ATTR_<attribute property name>

The order type attributes only apply to Action of Create and will apply to an entire order (in the case of multi-line orders). For multi-line orders: if more than one value is sent for the same order type attribute property, the last value provided will be used.

When using attributes, please contact customer support for the specific attribute property name to use in the Bulk Data file header. Only attribute display names are visible within the IDI platform and may not match the corresponding property name.

File Format

General Format

The following general characteristics apply to the Feature import files:

File naming convention must be *.csv
An identifier row is required (1^st row)
A header listing field names is required (2^nd row)
The header must be followed by one or more comma-delimited detail records
Place quotes (“) around any text fields containing a comma
Empty (non-required) fields are acceptable
The columns are not required to appear in a specific order. The order for a specific file is defined by the header record
You do not have to include all columns in an import file

Import Identifier

The first row of the file must have the file format identifier, starting in the first position of the first row. For the feature import, the identifier is:

FORMAT:IDI/CostGuardBulkData/Feature

Header Record

The second row of the import file must contain the appropriate column names. The column names are listed in the Record Layout section of this document. The columns do not need to appear in a specific order. Import files do not need to include all of the columns, only the columns that contain data to be imported are necessary. The field names must match exactly as listed in the layout.

Clear Values

The ability to clear previously set data is supported when Action = Modify. This includes product attribute values. To clear data, the record must contain @[System.Clear] as the field value.

Attempts to clear data for Boolean or required fields will result in an error.

Record Layout

The third row and beyond contain the feature records to process.

Field Formats:

Boolean:
True: 1, Yes, or True (case insensitive)
Any other value is interpreted as False
Date: YYYY-MM-DD or YYYY/MM/DD

Field	Data Type	Required for Create	Required for Modify	Description
AccountNumber	Text	Yes	No	Account number of the customer. Applicable only when Action = Create
Action	Text	No	Yes	Indicates the operation to perform when importing. Valid Values: Create, Modify When not specified, defaults to Create.
ATTRORD_*	Text	No	N/A	Contains the value of an attribute property for the order being created. There may be zero or more order attribute fields provided in an import record. See Attributes section above. Applicable only when Action = Create
ATTR_*	Text	No	No	Contains the value of an attribute property for the feature being added or modified. There may be zero or more attribute fields provided in an import record. See Attributes section above.
AutoRenew	Boolean	No	N/A	For a contract, whether the contract should auto-renew or not. This is ignored when Action = Modify
BillingStatus	Text	N/A	No	Applicable only when Action = Modify Valid Values: Billing, Not Billing
Charge	Decimal	No	No	Charge of the feature (overrides the charge configured for the feature in the Product Catalog)
Cost	Decimal	No	No	Cost of the feature (overrides the cost configured for the feature in the Product Catalog)
Description	Text	No	N/A	Optional text to override the default system-generated description for the feature. Only applicable when Action = Create.
DisplayNoteOnDirectInvoice	Yes/No	No	N/A	For orders created using a Starting Block with a Start As Option of Direct Invoice, when this field is true, the Note field for this item will be displayed on the Direct Invoice near the item’s description. Note: This field only applies to Retail Products in a Direct Invoice Order that are marked as Allow Direct Invoicing, and only applies for Create action.
EndDate	Date	No	No	End date of the feature
FeatureID	Integer	N/A	Yes	FeatureID/NonUsgSvcID for the assigned instance of the feature being modified Applicable only when Action = Modify
OrderTypeID	Integer	Yes	N/A	ID of the order type for the order that is created Applicable only when Action = Create Note: This is not required when StartingBlockID is specified, and the starting block has an order type configured.
Note	Text	No	No	Optional text to include with the feature
Quantity	Integer	Yes	No	Quantity of the feature
ServiceID	Integer	No	N/A	ID of the service to which this feature should be associated Applicable only when Action = Create
ServiceNumber	Text	No	N/A	Service number of the service to which this feature should be associated. Applicable only when Action = Create
ServiceTypeSKU	Text	No	N/A	SKU of the service type of the service to which this feature should be associated. Applicable only when Action = Create
ShippingAddress1	Text	No	N/A	Address line 1 associated with the shipping contact.. Only applicable when Action = Create.
ShippingAddress2	Text	No	N/A	Address line 2 associated with the shipping contact.. Only applicable when Action = Create.
ShippingAddress3	Text	No	N/A	Address line 3 associated with the shipping contact.. Only applicable when Action = Create.
ShippingContactID	Text	No	N/A	ID of an existing customer contact to use as the shipping contact. Note: When supplied, all other shipping information is ignored. Only applicable when Action = Create.
ShippingCity	Text	No	N/A	City associated with the shipping contact. .Only applicable when Action = Create.
ShippingCompanyName	Text	No	N/A	Company name associated with the shipping contact. Only applicable when Action = Create.
ShippingCountry	Text	No	N/A	Country associated with the shipping contact. Only applicable when Action = Create.
ShippingCounty	Text	No	N/A	County associated with the shipping contact. Only applicable when Action = Create.
ShippingEmailAddress1	Text	No	N/A	Email address associated to the shipping contact. Only applicable when Action = Create.
ShippingEmailAddress2	Text	No	N/A	Email address associated to the shipping contact. Only applicable when Action = Create.
ShippingEmailAddress3	Text	No	N/A	Email address associated to the shipping contact. Only applicable when Action = Create.
ShippingEmailType1	Text	No	N/A	Indicates the type of email of the shipping contact. Valid Values: ‘Home’, ‘Work’. Only applicable when Action = Create.
ShippingEmailType2	Text	No	N/A	Indicates the type of email of the shipping contact Valid Values: ‘Home’, ‘Work’. Only applicable when Action = Create.
ShippingEmailType3	Text	No	N/A	Indicates the type of email of the shipping contact. Valid Values: ‘Home’, ‘Work’. Only applicable when Action = Create.
ShippingFirstName	Text	No	N/A	First name associated with the shipping contact. Only applicable when Action = Create.
ShippingLastName	Text	No	N/A	Last name associated with the shipping contact. Only applicable when Action = Create.
ShippingMiddleInitial	Text	No	N/A	Middle initial associated with the shipping contact. Only applicable when Action = Create.
ShippingName	Text	No	N/A	Name associated with the shipping information. Only applicable when Action = Create.
ShippingNote	Text	No	N/A	Notes associated with the shipping contact. Only applicable when Action = Create.
ShippingPhoneNumber1	Text	No	N/A	Phone number associated with the shipping contact. Only applicable when Action = Create.
ShippingPhoneNumber2	Text	No	N/A	Phone number associated with the shipping contact. Only applicable when Action = Create.
ShippingPhoneNumber3	Text	No	N/A	Phone number associated with the shipping contact. Only applicable when Action = Create.
ShippingPhoneNumber4	Text	No	N/A	Phone number associated with the shipping contact. Only applicable when Action = Create.
ShippingPhoneType1	Text	No	N/A	Indicates the type of phone number of the shipping contact. Valid Values: ‘Home’, ‘Work’, ‘Mobile’, ‘Fax’, ‘Pager’. Only applicable when Action = Create.
ShippingPhoneType2	Text	No	N/A	Indicates the type of phone number of the shipping contact. Valid Values: ‘Home’, ‘Work’, ‘Mobile’, ‘Fax’, ‘Pager’. Only applicable when Action = Create.
ShippingPhoneType3	Text	No	N/A	Indicates the type of phone number of the shipping contact. Valid Values: ‘Home’, ‘Work’, ‘Mobile’, ‘Fax’, ‘Pager’. Only applicable when Action = Create.
ShippingPhoneType4	Text	No	N/A	Indicates the type of phone number of the shipping contact. Valid Values: ‘Home’, ‘Work’, ‘Mobile’, ‘Fax’, ‘Pager’. Only applicable when Action = Create.
ShippingState	Text	No	N/A	State associated with the shipping contact. Only applicable when Action = Create.
ShippingValidateAddress	Yes/No	No	N/A	Indicates if the shipping contact address should be validated. Default value is false When true, address validation errors will prevent the order from being created. Only applicable when Action = Create..
ShippingZipCode	Text	No	N/A	Zip code associated with the shipping contact. Only applicable when Action = Create.
SKU	Text	Yes	Yes	SKU for the feature being added.
StartDate	Date	No	No	The start date of the feature. If this value is not specified for an action of Create, the current date will be used.
StartingBlockID Note: Available with version 24.7 or later.	Integer	No	N/A	When specified in a row, use this starting block to start the order for that row. Note: Applicable only when Action = Create. The following rules apply: Order Type: If order type has been specified in the row, it will take precedence over the Order Type configured on the starting block. if order type has not been specified in the row, use the starting block’s order type if one has been configured for it; otherwise, throw an error. Tendering: If an order’s total (Subtotal + TaxSubtotal as determine by the Checkout operation) is greater than 0, add BTA tender (with a tender status of Open) to the order for the total amount. Receipt: Generate a receipt for Direct Invoice orders, or if the total amount is greater than 0. Receipt Doc Storage category: Direct Invoice for DI Orders and Web Receipt for all others.
StartNewOrder	Boolean	No	N/A	Whether or not a new order should be created, starting with the current line item. Note that populating this will override the default behavior where sequential line items for the same AccountNumber and OrderTypeID are included in the same order. Applicable only when Action = Create
WholesaleCost	Decimal	No	No	The wholesale cost of the feature (overrides the wholesale cost configured for the feature in the Product Catalog).