(2022.1) Service Order Imports
- Brian Dixon
- Amber Cowles (Deactivated)
Capability
This Import allows the User to INSERT or UPDATE existing Service Orders or INSERT new Service Order Actions.
Matches On
The Service Order Import attempts to match based on the SD Number. There are several valid values for SD Number and behaviors associated with each.
PREVIOUS
The Keyword PREVIOUS assigns the current line of the Import File record to UPDATE the last successfully saved Order with a new Child Action.
CREATE
The Keyword CREATE assigns the current line of the Import File record to INSERT a new Service Order record.
PREVIOUS_ACTION
The Keyword PREVIOUS_ACTION assigns the line of the Import record to UPDATE the last successfully saved Action with new Child data such as the GLA.
SD Number
Passing in a valid SD Number like 'SO201700001' prompts the Service Order Import to match on that number for an UPDATE. The SD Number must exist or the Import causes an error.
Fields
SD Number
Required
Datatype is String.
See the Matches On section for information about allowable values.
Service Rep
Required
Datatype is String.
It can be specified by Customer Number or both the First Name and Last Name.
The Service Rep MUST be an existing Contact with a Type of Service Rep.
Service Rep Customer Number
Datatype is String.
Service Rep First Name
Datatype is String.
MUST be used with Service Rep Last Name.
Service Rep Last Name
Datatype is String.
MUST be used with Service Rep First Name.
Due Date
Datatype is Date-Time.
Set Date Format in the Column Mapping Format Mask field.
Description
Datatype is String.
Status
Datatype is String.
Default value: Pending
If the Import is attempting an INSERT, the only valid value is Pending
If the Import is attempting an UPDATE, either Pending or Hold can be used.
ALL other values will cause an error.
Owner
Either an Owner Contact or Owner Department Hierarchy should be provided.
If they are both provided, an error is generated.
The Owner set on the Order applies to all child Actions unless an Action has an Owner otherwise specified.
Owner Contact
Datatype is String.
This is specified by Customer Number only NOT First Name or Last Name.
All Owners Contact must be Customer Type Contacts.
Owner Department Hierarchy
Datatype is Hierarchical String or String.
The value for this field can be the full Hierarachial Path, or it can be just the last part of the Path. If you provide only the last part, then there is a chance that there could be duplicate values in the database. If duplicate values are found, then you will get an error.
The Import does not accept the Department Hierarchy Name.
Requestor
This enters a Requestor into the Service Order item.
This can be specified by Customer Number or both the First Name and Last Name.
Requestor Customer Number
Datatype is String.
Requestor First Name
Datatype is String.
MUST be used with Requestor Last Name.
Requestor Last Name
Datatype is String.
MUST be used with Requestor First Name.
Associated Project
Datatype is String
Default value: blank
The provided value for this field must be an existing Project Service Desk Number.
Impact
Datatype is String.
Default value: Off
Valid values are blank (Off), Low, Medium, and High.
Note: You cannot provide the value 'Off'. You have to provide a blank, and it is displayed as 'Off'.
Any other values will cause an error.
Urgency
Datatype is String.
Default value: Off
Valid values are blank (Off), Low, Medium, and High.
Note: You cannot provide the value 'Off'. You have to provide a blank, and it is displayed as 'Off'.
Any other values will cause an error.
Default GLA
Datatype is Hierarchical String.
This sets the Action Default GLA in the Order's GLA tab.
Note: This is ignored if the SDA_ALLOW_MULTIPLE_DEFAULT_GLAS Configuration Option is set to True.
Child Records
Actions
Service Order Action fields. These fields can be Required, Optional, or Not Allowed. This can depend on the Action Type. It is assumed all of these are optional unless specified differently.
Action
Required if adding a Service Order Action.
Datatype is String.
Valid Actions are Add, Remove, Move, Upgrade/Downgrade, Miscellaneous, and Task.
If this field is blank, all other Actions fields must be blank as well
Action Service ID
Conditionally Required
Datatype is String.
Not Required on Add Actions.
If the Action is Add, the Service ID in the Import File MUST be set to the Available status.
If the Service ID is Available when the Import runs, the Status changes to Pending Order.
If the existing Service Catalog for the Service ID is not Assignable, an error generates.
The provided value can be formatted, unformatted, or it can be a Service Alias value.
NOT allowed for use on Task Actions.
Action Service RECID
Datatype is Number.
Default is blank.
This is used to specify the Service Record for Services that have a blank Service ID.
If this is provided, the provided value must be a valid existing Service RECID.
If it is not, it will cause an error.
If an Action Service RECID value is provided, the Action Service ID field will be ignored.
Action Serv Catalog
Datatype is Hierarchical String.
Conditionally Required
Required on Add, Upgrade/Downgrade, and Task Actions.
Ignored for any other Actions.
If the Action is set to Task, the Service Catalog MUST also be of type Task.
Action Location
Conditionally Required for Add Location Actions.
Conditionally Required for Add Actions if the Service Catalog's Location Required flag is set to True.
Datatype is Hierarchical String.
NOT allowed for use on Task Actions.
Optional for all other Change Actions.
Action Due Date
Datatype is String.
Set Date Format in the Column Mapping Format Mask field.
If not provided, this is calculated based on SLA.
Follows the typical rules for Due Date on Actions.
Action New Service ID
Datatype is String.
This is only used for Service ID Actions and are ignored for all other Action Types.
Action Swap Service ID
Datatype is String.
This is only used for Swap Actions and is ignored for all other Action Types.
Action Swap Service RECID
Datatype is Number.
Default is blank.
This is used to specify the Swap Service Record for Services that have a blank Service ID.
If this is provided, the provided value must be a valid existing Service RECID.
If it is not, it will cause an error.
If an Action Swap Service RECID value is provided, the Action Swap Service ID field will be ignored.
Action Reference
Datatype is String.
Owner field
Only one Owner should be provided, either the Contact or Department Hierarchy.
If they are both provided, it causes an error.
If the Owner of an individual Action is not provided, the Owner from the Order applies to the Action.
An Owner is Required for Add Actions
Action Owner Contact
Datatype is String.
Takes precedence on the Action if an Owner is specified on the Order.
This is specified by Customer Number not first name or last name.
All Contact Owners must be Customer Type Contacts.
Action Owner Department Hierarchy
Datatype is Hierarchical String or String.
Takes precedence on the Action if an Owner is specified on the Order.
The value for this field can be the full Hierarachial Path, or it can be just the last part of the Path. If you provide only the last part, then there is a chance that there could be duplicate values in the database. If duplicate values are found, then you will get an error.
Action SLA Catalog
Datatype is Hierarchical String.
Must match the SLA Description field of an existing SLA Catalog.
The Import does NOT create this record.
Action Service Host
Datatype is String.
Required for Add Actions with a Service Catalog type of Phone.
This field is optional for all Action types.
Is ignored for Remove Actions.
Use of Service Host on a Task Action is NOT allowed.
Action Urgency
Datatype is String.
Permitted values are Null, Low, Medium, and High.
Any other values are converted to Null.
Follows the typical rules for Urgency on Actions.
Action SDC
Datatype is String.
Action Location Type
Datatype is String.
Conditionally Required if the provided Action Location Name exists with multiple Types.
Permitted values are from the LOCATION_TYPE List Values.
This field is used for the Action Location lookup if provided.
Report 911 flag
Datatype is Boolean.
Only set for Phone type Services.
NOT allowed for use on Task Actions.
See Service Order Imports Notes section of this wiki for more information about the behavior of this field.
Directory flag
Datatype is Boolean.
Only set for Phone type Services.
NOT allowed for use on Task Actions.
See Service Order Imports Notes section of this wiki for more information about the behavior of this field.
Essential flag
Datatype is Boolean.
NOT allowed for use on Task Actions.
See Service Order Imports Notes section of this wiki for more information about the behavior of this field.
Billable flag
Datatype is Boolean.
NOT allowed for use on Task Actions.
See Service Order Imports Notes section of this wiki for more information about the behavior of this field.
Auth Code Type
Datatype is String.
Permitted values are from the AUTH_CODE_TYPE List Values.
Only set for Auth Code type Services.
See Service Order Imports Notes section of this wiki for more information about the behavior of this field.
Classes of Service
Datatype is String.
Permitted values are Class of Service Codes from the Class of Service grid.
Only set for Auth Code type Services.
See Service Order Imports Notes section of this wiki for more information about the behavior of this field.
Bandwidth
Datatype is String.
Permitted values are from the BANDWIDTH List Values.
Only set for Backbone and Data type Services.
See Service Order Imports Notes section of this wiki for more information about the behavior of this field.
Rating Group
Datatype is String
Default blank
Permitted values are from the RATING_GROUP List Values.
This is only used for Phone and Auth Code type Services.
The Rating Group field can only be used if it has been turned on in the configuration file.
See the Service Order Imports Notes section of this wiki for more information about the behavior of this field.
GLAs
If the GLA is provided, it can apply to a Service Order record or to an Action. By default, the GLA data will always apply to the Service Order. The only way to make it apply to an Action is to use the "PREVIOUS_ACTION" keyword in the "SD Number" field. This means it will require at least two input lines to apply a GLA to an Action. One line to create the Action, and the next line(s) with the PREVIOUS_ACTION keyword and all blank Action fields to apply the GLAs.
GLA
Datatype is Hierarchical String.
If the GLA is blank, the GLA Expense Type, GLA Percent, and Default GLA Flag are all ignored.
GLA Expense Type
Datatype is String.
The Default Value is Default.
Permitted values are from EXPENSE_TYPE List Values: Default, Usage, Equipment, and Labor.
Values added to EXPENSE_TYPE List Values can also be used.
If a value provided by the Import File does NOT match an existing value, a warning is generated and the value does not INSERT for the EXPENSE_TYPE.
GLA Percent
Datatype is String.
Default Value is 100.
Permitted values are whole integers between 1-100.
Can be provided as an array to allow multiple GLAs.
Provided values MUST add up to 100.
If multiple GLAs are provided with no percent values, the percents are divided between the provided GLAs as evenly as possible.
Default GLA Flag
Datatype is String.
Default value is False.
This is only used if the SDA_ALLOW_MULTIPLE_DEFAULT_GLAS Configuration Option is set to True.
Flags
SERVICE_ALIAS_SEARCH
Datatype is String
Default First
The provided Service ID value might match a Service ID, and also match an Alias value of a different Service ID. This flag tells the import which result to use. You can set the flag to one of these 3 values:
"First" The Alias value will be used first.
"Last" The Alias value will be used last.
"None" The Alias value will not be used at all.
ACTION_CABLE_ARRAY
If this flag is used, it must be assigned from an array in the Conditional Logic. An array is being used to allow you to specify multiple Cable operations on one input line. Here is an example of how to assign the flag, and all of the allowed array indexes for 2 Cable operations.
[FLAGS.ACTION_CABLE_ARRAY] = array( // first action, using csv fields 50-67 array( "Flag" => [50], "Action" => [51], "Line_Number" => [52], "Notes" => [53], "Backbone_Service_ID" => [54], "Backbone_Service_Recid" => [55], "From_Eqp_ID" => [56], "From_Eqp_Location" => [57], "From_Eqp_Location_Type" => [58], "From_Port" => [59], "From_Port_Side" => [60], "Cable_Name" => [61], "Pair_Strand" => [62], "To_Eqp_ID" => [63], "To_Eqp_Location" => [64], "To_Eqp_Location_Type" => [65], "To_Port" => [66], "To_Port_Side" => [67], ), // optional second action, using csv fields 68-85 array( "Flag" => [68], "Action" => [69], "Line_Number" => [70], "Notes" => [71], "Backbone_Service_ID" => [72], "Backbone_Service_Recid" => [73], "From_Eqp_ID" => [74], "From_Eqp_Location" => [75], "From_Eqp_Location_Type" => [76], "From_Port" => [77], "From_Port_Side" => [78], "Cable_Name" => [79], "Pair_Strand" => [80], "To_Eqp_ID" => [81], "To_Eqp_Location" => [82], "To_Eqp_Location_Type" => [83], "To_Port" => [84], "To_Port_Side" => [85], ), );
Using this array method, any number of Cable operations can be provided.
Following is a list of the array indexes that are allowed. All of these are optional except for the "Flag".
"Flag"
This value is Required for any Cable operation. This tells the import process what you are trying to do. Allowed values are: Add, Edit, Delete, DeleteAdds, DeleteAll.
Use the Add flag to add new Cable actions.
Use the Edit flag to edit specific existing Cable actions. You should also specify an Action and Line Number to determine what Cable action to edit.
Use the Delete flag to delete specific existing Cable actions. You should also specify an Action and Line Number to determine what Cable action to edit.
Use the DeleteAdds flag to delete all existing Cable add actions from the Service Order Action.
Use the DeleteAll flag to delete all existing Cable actions from the Service Order Action.
Note that when any Service Order Action is created on an existing Service, all of the existing Cable information on that Service is automatically added to that Service Order Action. These flag operations can be used to modify those existing values.
"Action"
Type of Cable Action. Allowed values are Delete, Out Backbone, Add, In Backbone.
This index is only used for Edit and Delete lookups. Any new lines are automatically Add actions. If this is not provided, it will default to "Add".
"Line_Number"
When Adding a Cable action, this is optional. If it is not provided, then the system will calculate the next Line Number.
When Editing or Deleting, this can be used to find the Cable action you want to affect. This is not needed if there is only one Cable action to pick from.
"Notes"
Cable Path Notes.
"Backbone_Service_ID"
An existing Backbone Service ID to add to a Cable Path.
"Backbone_Service_Recid"
An alternate method to specify an existing Backbone Service, useful if the Service ID is blank.
"From_Eqp_ID"
Cable Path From Equipment ID.
"From_Eqp_Location"
From Equipment Location, useful if the Equipment ID is not unique.
"From_Eqp_Location_Type"
From Equipment Location Type, useful if the Location Name is not unique.
"From_Port"
From Equipment Port.
"From_Port_Side"
From Equipment Port Side. This is required if a From Port is specified.
"Cable_Name"
Cable Name to attach to the Path.
"Pair_Strand"
Pair/Strand to attach to the Path. If this is specified, then the Cable Name is also required.
"To_Eqp_ID"
Cable Path To Equipment ID.
"To_Eqp_Location"
To Equipment Location, useful if the Equipment ID is not unique.
"To_Eqp_Location_Type"
To Equipment Location Type, useful if the Location Name is not unique.
"To_Port"
To Equipment Port.
"To_Port_Side"
To Equipment Port Side. This is required if a To Port is specified.
Errors
When an Import Line fails, it is usually because the Line falls into one of the following categories:
The value provided from another table was not found within the Database
The value provided from another table is Inactive
A blank value was provided, for a field with a required value
The value provided is not acceptable for the record type being created
The System was unable to save the record
Notes
The Service Order Source field CANNOT be set in Import. It is automatically set to Import on INSERT and unchanged for UPDATE.
The following fields can be set manually in an Import File: Report 911 flag, Directory flag, Essential flag, Billable flag, Auth Code type, Classes of Service, Bandwidth, and Rating Group.
If the fields are left blank, not Required, and the Action type is Add, the fields will be populated by the Service Catalog. If the fields are left blank, not Required, and the Action type is not Add, the fields will be populated by the existing Service.
UDF Associations
User Defined Fields on any given Import are all handled the same way with Conditional Logic. For more information about adding a UDF to the Import see, the (2022.1) User Defined Fields section of the Imports main page. When Service Order Upgrade/Downgrade Actions are created by the Import, the "old" UDF values from the Service are automatically stored on the Action record.