Document toolboxDocument toolbox

(v1) .Service Desk Imports v2019.4

Owned by David Engblom
Apr 16, 2024
8 min read

Capability

This Import allows the User to INSERT or UPDATE existing Service Desk items (such as Orders or Requests) or INSERT new Service Desk Actions.

Matches On

The Service Desk 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 Desk 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.

Type

Required

Datatype is String.

Currently Service Order is the only valid type for Imports, but more may be added in a future version.

Service Rep

Required

Datatype is String.

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 String.

Set Date Format in the Column Mapping Format Mask field.

Description

Datatype is String.

Status

Datatype is String.

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 are ignored.

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 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 Desk 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.

Urgency

Datatype is String.

Valid values are Null, Low, Medium, and High.

Any other values are converted to Null.

Default GLA

Datatype is 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

Datatype is String.

Valid Actions are Add, Remove, Move, Upgrade/Downgrade, and Task.

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.

NOT allowed for use on Task Actions.

Action Serv Catalog

Datatype is String.

Conditionally Required

Required on Add, Upgrade/Downgrade and Task Actions.

Ignored for any other Actions.

Only Service IDs with a Service Catalog that has the Assignable flag set to True are allowed.

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 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 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 String.

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

Action SLA Catalog

Datatype is 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.

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 Notes section of this wiki for more information about this fields behavior.

Directory flag

Datatype is Boolean.

Only set for Phone type Services.

NOT allowed for use on Task Actions.

See Notes section of this wiki for more information about this fields behavior.

Essential flag

Datatype is Boolean.

Used by all Services.

NOT allowed for use on Task Actions.

See Notes section of this wiki for more information about this fields behavior.

Billable flag

Datatype is Boolean.

Used by all Services.

NOT allowed for use on Task Actions.

See Notes section of this wiki for more information about this fields behavior.

Auth Code Type

Datatype is String.

Permitted values are from the AUTH_CODE_TYPE List Values.

Conditionally Required if the Service type is Auth Code and the Action type is Add.

See Notes section of this wiki for more information about this fields behavior.

Classes of Service

Datatype is String.

Permitted values are from the Class of Service grid.

Conditionally Required if the Service type is Auth Code and the Action type is Add.

See Notes section of this wiki for more information about this fields behavior.

Bandwidth

Datatype is String.

Permitted values are from the BANDWIDTH List Values.

See Notes section of this wiki for more information about this fields behavior.

GLAs

If the GLA is provided, it can apply to a Service Desk record or to an Action.

GLA

Datatype is String.

This is a full sequence of GLA Components separated by the GLA_CONCATENATOR.

Multiple levels of a hierarchy "path" (like Locations, GLAs, and Catalogs) are connected by the HIERARCHYPATH_SEPARATOR string.

The default value for this string is right angle-brace (>) with a space on either side: " > ".

When importing nested Locations, the separator you use for each level of the hierarchy must match the concatenator string.

For example, Site A > Building B > Room C.

Can be provided as an array to allow multiple GLAs.

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.

Errors

The following errors display if the Service Desk Import fails:

  • Error : Invalid provided Service Rep name <firstName> <lastName>
  • Error : Invalid provided Service Rep Customer Number <customerNumber>
  • Error : Invalid provided Default Owner name <firstName> <lastName>
  • Error : Invalid provided Default Owner customer number <customerNumber>
  • Error : Invalid provided Requestor name <firstName> <lastName>
  • Error : Invalid provided Requestor Customer Number <customerNumber>
  • Error : Invalid provided Action Owner name <firstName> <lastName>
  • Error : Invalid provided Action Owner Customer Number <customerNumber>
  • Error : Invalid Default Owner Dept Hierarachy '<deptHierarchy>'
  • Error : Invalid Action Owner Dept Hierarachy '<deptHierarchy>'
  • Error : SD Number PREVIOUS specified but no previous successful save
  • Error : Invalid Service Desk Number '<SD_NUMBER>'
  • Error : Invalid Service Desk Status. Only Pending is allowed for new Service Desk records.
  • Error : Invalid Service Desk Status. Only Pending or Hold is allowed for Service Desk updates.

"Error : Invalid Service Desk Type '<SD_TYPE>>'

  • Error : Service Desk Type is blank
  • Error : Service Rep is blank for new Service Desk record
  • Error : Invalid Default GLA '<DEFAULT_GLA>'
  • Error : Default Owner Contact and Dept Hierarchy were both specified. Only one is allowed.
  • Error : SD Number PREVIOUS_ACTION specified but no previous successful Action save
  • Error : The Import process cannot Import that Action Type at this time
  • "Error : Missing required Action type
  • Error : No Service ID specified
  • Error : Inactive Service Catalog '<SERV_CATALOG>'
  • Error : Invalid Service Catalog '<SERV_CATALOG>'
  • Error : Missing Required Service Catalog value for Add or Upgrade action
  • Error : Invalid Swap Service ID '<SWAP_SERVICE>'
  • Error : Action Owner Contact and Dept Hierarchy were both specified. Only one is allowed.
  • Error : Invalid SLA Catalog '<SLA_CATALOG>'
  • Error : Invalid Service Host '<SERVICE_HOST>'
  • Error : Invalid Location '<LOCATION>'
  • Error : SDC '<SDC>' is not valid for this Action
  • Error : Invalid SDC '<SDC>'
  • Error : Invalid Service ID
  • Error : Missing Service ID for Action
  • Error : Service Catalog <SERV_CATALOG> is not assignable
  • Error : Service Catalog <SERV_CATALOG> does not match existing Service ID
  • Error : Service Host is required for Phone Add Actions
  • Error : Provided Service Host not permitted for this Service Catalog
  • Error : Provided Location not permitted for this Service Catalog
  • Error : Missing required Location for Add Action for this Service Catalog
  • Error : Existing Service ID is not Available for Add Action
  • Error : New Service ID provided for none Service ID Action
  • Error : Swap Service ID provided for none Swap Action
  • Error : The parent Service Order has a status of <Void, Complete, Finalized, or Billed>. No other Actions may be added to this Order.
  • Error : Service Catalog types do not match
  • Error : Provided Location not permitted for this Service Catalog
  • Error : Service Catalog does not match Service pool
  • Error : Service Catalog Service ID formats do not match
  • Error : Different count of GLAs and GLA percents
  • Error : Some GLA Percents are blank
  • Error : Some GLA Percents are out of range (1 to 100)
  • Error : Some GLA Percents are not whole numbers
  • Error : GLA Percents do not add up to 100
  • Error : Previous Service Desk save failed, so cannot save Service Desk GLA
  • Error : Previous Service Desk Action save failed, so cannot save action GLA
  • Error : Blank GLA
  • Error : Invalid GLA '<gla>'
  • Error : Failed to save Service Desk record; <errorMessage>
  • Error : Failed to save Service Desk Action record; <errorMessage>
  • Error : Previous Service Desk save failed, so cannot save Service Desk GLA
  • Error : Previous Service Desk Action save failed, so cannot save action GLA
  • Error : Failed to save Service Desk GLA record; <errorMessage>
  • Error : Invalid Action Location Type '<LOCATION_TYPE>'

Notes

The Service Desk 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, and Bandwidth.

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 Desk Upgrade/Downgrade Actions are created by the Import, the "old" UDF values from the Service are automatically stored on the Action record.

Help Desk Portal - Email: help@pcr.com - Phone: 616.259.9242