(v1) .Service Order Imports v2021.1

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.

Blank value - (Null)

Passing in a blank value or Null causes the Import to create a new Order record.

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.

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.

The full Department Hierarchy Path and Code value should be provided.

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 (v1) 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.

Takes precedence on the Action if an Owner is specified on the Order.

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 (v1) 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.

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.

Errors

When an Import Line fails, it is usually because the Line falls into one of the following categories:

1. The value provided from another table was not found within the Database

2. The value provided from another table is Inactive

3. A blank value was provided, for a field with a required value

4. The value provided is not acceptable for the record type being created

5. 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 (v1) 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.