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.
Link:
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.
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 (1st row)
A header listing field names is required (2nd 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 import identifier is optional if you import files via the Bulk Import web module. The correct identifier is automatically applied by selecting the type of import.
If you import using the file automation method by uploading files and placing them on the file server, 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 import file must contain the appropriate column names. This is typically the first row when using the Bulk Import module. It is the second row if you use the file automation method. 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.
Custom Properties
When adding features (Action = Create), custom property values can be provided for both the order type and the product. The header record must list a field for each unique custom property name that is being assigned a value in the file.
When modifying a feature (Action = Modify), only the product custom properties apply.
In the file header record, the custom property fields must be added using the following syntax:
Order Type: ATTRORD_<property name>
Product: ATTR_<property name>
The order type properties 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 custom property, the last value provided will be used.
When using custom properties, please contact customer support for the specific property name to use in the Bulk Data file header. Only property display names are visible within the IDI platform and may not match the corresponding property name.
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.
FieldFormats:
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 a custom property for the feature being added or modified. There may be zero or more custom property fields provided in an import record. See the Custom Properties 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.
|
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 | 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.
|
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
| Integer | No | N/A | When specified in a row, use this starting block to start the order for that row.
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). |