Work Order Interface

Work Order Messages are sent to the q.se.ps.azure.data.messages.workordermessage Queue on the Tenant Service Bus. If a Dynamic Workflow is configured to preprocess the message, they should be sent to the q.se.ps.azure.data.messages.workordermessage.pre Queue instead. If you do not want to update a certain property, do not include it in the message, unless it is marked as required. Setting a property to null in the message will null it out in DXI. The default behavior is if the Work Request does not exist, it will be created, otherwise it will be updated. However, if EnforceCreate is set to true in the configuration, then the behavior changes and an error will be generated and the message dead lettered if a create is sent and the Work Request already exists or an update is sent and the Work Request does not exist. When updating design properties, e.g. Design Notes, Design Attributes, Assignment Status, etc. if no Design ID is supplied, all Designs on the Work Request are updated. A special interface exists for error messages. Simply add the error as an attribute named Errors (configurable) with the following format: [ { "id": "Err1", "message": "error message 1", "date": "2022-02-14T22:18:32Z" } ] An id is not needed for the error, but can be helpful if you do not want to flood the user with the same errors or want to delete the error. Errors will not display in DXI OOTB, but the adaptive card can be updated in Solution Center to show them. Reach out to your project team for samples.

{ "diagnostic": false, "workOrderId": 987654321, "workflowSessionId": null, "designId": "6e25539d-4424-49cc-8796-6481256722eb", "designName": null, "WONumber": "WO1234567", "name": null, "feederIds": null, "operationType": "Create", "WOStatus": "WAPPR", "createWorkRequestOnly": false, "RPAppointmentDate": null, "CSONumber": "X4567890", "WODescription": "Sample Description", "customerName": "Jane Smith", "customerAddress": "123 Main St", "city": "Schneiderville", "latitude": 0.0, "longitude": 0.0, "customerPhoneNumber": "1234567890", "contactName": "John Smith", "contactPhone": "1234567890", "businessPhone": "1234567890", "planner": "jdoe@se.com", "plannerAssignmentStatus": null, "workRequestNotes": "Sample Notes", "designNotes": null, "domain": "Electric", "workRequestType": "Residential", "workDepot": "FTC", "location": null, "transactionId": "0CDFF8FF-868B-459F-B3D4-39B7721776EB", "designAttributes": [ { "key": "SampleAttribute", "value": "Sample Value" } ], "attributes": [ { "key": "SampleAttribute", "value": "Sample Value" } ] }

A message containing a MultiSpeak Work Order message converted to JSON

The Work Order from the WMS. Used to create and manage a Work request, Design, and Assignment in DXI For updates, values will overwrite the values in DXI, unless stated otherwise.

The unique ID or name of the work order

The JSON message

A unique ID for this message for logging purposes

The WorkOrderId of the message

The session ID for the message. This is needed for putting the message in a Queue

If set to true, performers an internal diagnostic. This is only meant to be used by the health monitoring service. It does not need to be set on the message.

The unique ID of the work order. Often the primary key in the WMS. [Required]

Gets or sets the workflow session identifier.

The ID of the Design in DXI. If a Design ID is not supplied, any Design related updates are done to all Designs on the DXI Work Request.

The Name of the design. If null, WoNumber is used for the name. For an update message, a valid DesignID must be supplied to update the DesignName. If the CreateWorkRequestOnly parameter is set to true, this parameter is ignored.

The Work Order Number. Used for the Name of the Design. Used as the second part of the Name of the Work Order, along with the Work Depot and CSO number. Name={WorkDepot} WO {WoNumber} CSO {CsoNumber} [Required]

Sets the Name of the Work Order. This will override the default Name containing the Work Order Number and CSO number, if the Name needs to be something different. Leave this null to use the standard naming convention.

The feeder IDs to extract, if this is an electric work order. If this is null and feeder extraction is being used, a spatial query will be performed to find the feeder IDs.

Informs the Integration what type of operation is intended Create - creates a work order, or updates, if it already exists Update - updates a work order, or creates it, if it does not exist Delete - deletes a work order Replace - deletes the work order and creates a new one (The main use case is if the XY changed and the GIS data needs extracted again, however, the user will lose any work) [Required]

Sets the Status on the Work Order that users can see. Special statuses trigger additional functionality: Complete(configurable) - Moves the Assignment to Complete, if it is not already. Sends the command to create a Session in GIS which will trigger a push to GIS when complete ReOpen(configurable) - ReOpens the Assignment, if it can be reopened. Close(configruable) - Closes the Assignment PushWRtoGIS - Sends the push to GIS command. This is only for troubleshooting purposes. [Required]

If true, only workrequest is created with no design and assignments.

Not used. Reserved for future functionality.

The CSO Number. Used as the last part of the Name of the Work Order, along with the Work Order Number and CSO number. If null, it is not added to the Name. Name={WorkDepot} WO {WoNumber} CSO {CsoNumber}

The description of the work order.

The name of the customer. Used to populate the Customer field on the work request in DXI. Null values can be ignored via configuration. Customer=Name: {CustomerName}, Phone: {CustomerPhoneNumber}, Contact Name: {ContactName}, Contact Phone: {ContactPhone}

The Address for the work order. Sets the first part of the Location in DXI. Location={CustomerAddress} {City} This value has no effect internally. It is just for the user's information.

The City for the work order. Sets the second part of the Location in DXI. Location={CustomerAddress} {City} This value has no effect internally. It is just for the user's information.

The latitude of the work order. The coordinate system is configurable. The default coordinate system is WGS84 [Required]

The longitude of the work order. The coordinate system is configurable. The default coordinate system is WGS84 [Required]

The phone number of the customer. Used to populate the Customer field on the work request in DXI. Null values can be ignored via configuration. Customer=Name: {CustomerName}, Phone: {CustomerPhoneNumber}, Contact Name: {ContactName}, Contact Phone: {ContactPhone}

The name of the contact for the work order. Used to populate the Customer field on the work request in DXI. Null values can be ignored via configuration. Customer=Name: {CustomerName}, Phone: {CustomerPhoneNumber}, Contact Name: {ContactName}, Contact Phone: {ContactPhone}

The phone number of the contact for the work order. Used to populate the Customer field on the work request in DXI. Null values can be ignored via configuration. Customer=Name: {CustomerName}, Phone: {CustomerPhoneNumber}, Contact Name: {ContactName}, Contact Phone: {ContactPhone}

Not used. Reserved for future functionality.

The email address of the user the work order should be assigned to. The user must be in DXI. If null, the work order will be unassigned.

Not used. Reserved for future functionality.

Sets the Design Notes on the work request in DXI.

Sets notes on designs

The Domain of the work order. The default is Electric, if not set. Electric Gas

The work request type of the work order. The default is Undefined, if not set Undefined Residential Commercial

The Work Depot. Used as the first part of the Name of the Work Order, along with the Work Order Number and CSO number. If null, it is not added to the Name. Name={WorkDepot} WO {WoNumber} CSO {CsoNumber}

Sets the Location of the Work Order. This will override the default Location containing the Customer Address and City, if the Location needs to be something different. Leave this null to use the standard Location convention. Location={Location}

A unique ID that will appear in all log messages related to this message. If null, a random GUID is generated.

Id is mainly used for logging. WoNumber is used because it is usually more human-readable or recognizable. WoNumber should not be null, but just in case it is, the WorkOrderId is used as a fallback.

Am auto generated list of the fields that were sent in the message.

Design Attributes can be just about any string supported by WMS. These are often used to map components to the correct subtype in GIS, map to GIS fields or to pass back to WMS.

Attributes can be just about any string supported by WMS. These are often used to map components to the correct subtype in GIS, map to GIS fields or to pass back to WMS.

Key Value attributes stored in messages

The Name of the attribute. Each Attribute should have a unique name.

The Value of the attribute.