logo
API docs by Redocly

Service Partner Gateway (v1.2.8)

Download OpenAPI specification:Download

E-mail: api@tuatahifibre.co.nz

Overview

The Service Partner Gateway (SPG) is used to exchange jobs and job updates between TFF and Service Partners.

SPG Overview

The notifications of new jobs and tasks are sent from SPG via Notifications Gateway (NGW). Service Partners must implement a Webhook API if they want to receive SPG Notifications.

The Workorders API is invoked by Service Partners to provide updates and details for workorders and tasks to SPG.

Updates must be send as events, which include the workorder(s) and task(s) being updated with all necessary details. The main method to submit an event to:

  POST /events

This is a generic method which accepts events on any type. The Workorders API also provides the alternative convenience methods for each event type. These convenience methods are simply wrapping a work order payload into an event-compliant object and forward it to the /event endpoint

Events flow

Accept or reject the Work Order

In reponse to a CreateWorkOrderEvent sent by TFF, Work Supplier must accept or reject the work order. To accept the work order, send 2 events:

  1. AcceptWorkOrderEvent (include reference to the SP's work order id), AND
  2. UpdateTaskStatusEvent (category:Open, state:Accepted)

To reject the work order:

  1. RejectWorkOrderEvent (rejectReason must be included)

Task has been scheduled

Once the Task is scheduled by the Work Supplier:

  • UpdateTaskScheduleEvent (start, end [,crNumber])

This event will automatically update the TFF Work Order status to SCHED

Status updates

Use the UpdateTaskStatusEvent to send updates on the progress:

  • UpdateTaskStatus (category:Active, state:EnRoute)
  • UpdateTaskStatus (category:Active, state:OnSite)
  • UpdateTaskStatus (category:Active, state:Started)

Adding information to the Work Order

Use the following methods to send additional information about the Work Order/Tasks (e.g. worklog entry) or attach files:

  • UpdateWorkOrderAdditionalInfosEvent(text)
  • UpdateWorkOrderFileAttachmentsEvent(filename, fileUrl)
  • UpdateTaskAdditionalInfosEvent(text)
  • UpdateTaskFileAttachmentsEvent(filename, fileUrl)

Task has been completed

To indicate physical completion, update task status and send the actuals

  1. UpdateTaskStatus (category:Active, state:PracticalCompletion), AND
  2. UpdateTaskOutcomesEvent (actuals)

After internal review, TFF will respond with a task status update event. Task will be closed with a "Complete" state, or closed as "Incomplete" if redo is required.

Putting work on old

To put task on hold, use a dedicated event and provide a reason:

  • PutOnHoldTaskEvent (category:OnHold, state:OnHold, reason:)

Resuming work

The work can be resumed by sending one of the following events:

  • UpdateTaskStatusEvent (category:Open, state:Accepted)
  • UpdateTaskStatusEvent (category:Active, state:EnRoute)
  • UpdateTaskStatusEvent (category:Active, state:OnSite)
  • UpdateTaskStatusEvent (category:Active, state:Started)
  • UpdateTaskScheduleEvent (start, end)

Cancelling the task

Tasks which are marked with workSupplierAllowedToCancel:true and are currently on hold can be cancelled by the Work Supplier by sending a CloseTaskEvent.

  • CloseTaskEvent (category:Closed, state:Cancelled, reason)

Event API

Send an event to the Service Partner Gateway

Send an event to the Service Partner Gateway. This is a generic method for sending events of any supported type.

Authorizations:
tff_oAuth_client_cred
header Parameters
X-Transaction-Id
string

Represents the unique message identifier associated with the Event.

Request Body schema: application/json
required
One of
eventId
string

When available, consumer can provide an event id linked to this event in their system

eventDateTime
string (common.datetime.cdatetime) (1|2\d{3})-(0[1-9]|1[012])-(0[1-9]|[12]\d|3[0...

LFC API Standard Date Time format The date and time in RFC3339 with 'Z' as tzd, microseconds optional, valid formats are ["yyyy-MM-dd'T'HH:mm:ssZ", "yyyy-MM-dd'T'HH:mm:ss.SSSZ" ]

eventType
required
string
Value: "AcceptWorkOrderEvent"

Event type

object (event.workorder.AcceptWorkOrderEvent)

Event sent by Service Partner to TFF to accept the Work Order assigned to them.

Responses

Request samples

Content type
application/json
Example
{
  • "eventId": "string",
  • "eventDateTime": "string",
  • "eventType": "AcceptWorkOrderEvent",
  • "workorder": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "cause": "string",
  • "details": [
    ]
}

Event Types

Accept Work Order

Authorizations:
tff_oAuth_client_cred
header Parameters
X-Transaction-Id
string

Represents the unique message identifier associated with the Event.

Request Body schema: application/json
wonum
required
string

Original work order id assigned to the Work Order by TFF.

required
object

The allocation details for an Accept Work Order.

Responses

Request samples

Content type
application/json
{
  • "wonum": "string",
  • "allocation": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "cause": "string",
  • "details": [
    ]
}

Reject Work Order

Authorizations:
tff_oAuth_client_cred
header Parameters
X-Transaction-Id
string

Represents the unique message identifier associated with the Event.

Request Body schema: application/json
wonum
required
string

Original work order id assigned to the Work Order by TFF.

required
object

The allocation details for a Reject Work Order.

Responses

Request samples

Content type
application/json
{
  • "wonum": "string",
  • "allocation": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "cause": "string",
  • "details": [
    ]
}

Update Task Status

Authorizations:
tff_oAuth_client_cred
header Parameters
X-Transaction-Id
string

Represents the unique message identifier associated with the Event.

Request Body schema: application/json
wonum
required
string

Original workorder Id assigned by TFF to the Work Order.

required
Array of objects (event.workorder.task.UpdateTaskStatusEvent)

A list of tasks associated with the Work Order.

Responses

Request samples

Content type
application/json
{
  • "wonum": "string",
  • "tasks": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "cause": "string",
  • "details": [
    ]
}

Put Task On Hold

Authorizations:
tff_oAuth_client_cred
header Parameters
X-Transaction-Id
string

Represents the unique message identifier associated with the Event.

Request Body schema: application/json
wonum
required
string

Original workorder id assigned to the work order by TFF

required
Array of objects (event.workorder.task.PutOnHoldTaskEvent)

A list of tasks associated with the WO.

Responses

Request samples

Content type
application/json
{
  • "wonum": "string",
  • "tasks": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "cause": "string",
  • "details": [
    ]
}

Cancel Task

Authorizations:
tff_oAuth_client_cred
header Parameters
X-Transaction-Id
string

Represents the unique message identifier associated with the Event.

Request Body schema: application/json
wonum
required
string

Original workorder id assigned to the work order by TFF

required
Array of objects (event.workorder.task.CloseTaskEvent)

A list of tasks associated with the WO.

Responses

Request samples

Content type
application/json
{
  • "wonum": "string",
  • "tasks": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "cause": "string",
  • "details": [
    ]
}

Add files to the Task

Authorizations:
tff_oAuth_client_cred
header Parameters
X-Transaction-Id
string

Represents the unique message identifier associated with the Event.

Request Body schema: application/json
wonum
required
string

Original work order id assigned to the Work Order by TFF.

required
Array of objects (event.workorder.task.UpdateTaskFileAttachmentsEvent)

A list of changed tasks.

Responses

Request samples

Content type
application/json
{
  • "wonum": "string",
  • "tasks": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "cause": "string",
  • "details": [
    ]
}

Add notes to the Task

Authorizations:
tff_oAuth_client_cred
header Parameters
X-Transaction-Id
string

Represents the unique message identifier associated with the Event.

Request Body schema: application/json
wonum
required
string

Original work order id assigned to the Work Order by TFF.

required
Array of objects (event.workorder.task.UpdateTaskAdditionalInfosEvent)

A list of changed tasks.

Responses

Request samples

Content type
application/json
{
  • "wonum": "string",
  • "tasks": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "cause": "string",
  • "details": [
    ]
}

Update Task Schedule

Send a new schedule for a single Task, or for every Task on the same Work Order.

Authorizations:
tff_oAuth_client_cred
header Parameters
X-Transaction-Id
string

Represents the unique message identifier associated with the Event.

Request Body schema: application/json
wonum
required
string

Original Id assigned by TFF to the Work Order.

required
Array of event.workorder.task.UpdateTaskScheduleEvent (object) or event.workorder.task.UpdateTaskAppointment (object)

A list of tasks associated with the Work Order.

Responses

Request samples

Content type
application/json
{
  • "wonum": "string",
  • "tasks": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "cause": "string",
  • "details": [
    ]
}

Send actuals

Represents an Update Work Order Task Outcomes Event

Authorizations:
tff_oAuth_client_cred
header Parameters
X-Transaction-Id
string

Represents the unique message identifier associated with the Event.

Request Body schema: application/json
wonum
required
string

Original Id assigned by TFF to the WO

required
Array of objects (event.workorder.task.UpdateTaskOutcomesEvent)

A list of tasks associated with the WO.

Responses

Request samples

Content type
application/json
{
  • "wonum": "string",
  • "tasks": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "cause": "string",
  • "details": [
    ]
}

Add notes to the Work Order

Represents an Update Work Order Additional Infos Event

Authorizations:
tff_oAuth_client_cred
header Parameters
X-Transaction-Id
string

Represents the unique message identifier associated with the Event.

Request Body schema: application/json
wonum
required
string

Original work order id assigned to the Work Order by TFF.

required
Array of objects (common.workorder.additionalInfo)

A list of additionalInfo records to be added to the Work Order.

Responses

Request samples

Content type
application/json
{
  • "wonum": "string",
  • "additionalInfos": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "cause": "string",
  • "details": [
    ]
}

Attach files to the Work Order

Represents an UpdateWorkOrderFileAttachments Event

Authorizations:
tff_oAuth_client_cred
header Parameters
X-Transaction-Id
string

Represents the unique message identifier associated with the Event.

Request Body schema: application/json
wonum
required
string

Original work order id assigned to the Work Order by TFF.

required
Array of objects (common.fileAttachment)

A list of file attachments to be added to the Work Order.

Responses

Request samples

Content type
application/json
{
  • "wonum": "string",
  • "fileAttachments": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string",
  • "cause": "string",
  • "details": [
    ]
}