Hello All
In terms of looking for and reserving appointments we made changes to the V4 specification.
So when looking for and reserving appointments (for us) it is in the context of completing the fulfilment of an order or fixing a problem.
In the V4 spec there was a related entity where you could refer to something like an order and that would imply the skills required.
One issue for us though is that we use this API as B2B integration and want customers to search for and reserve an appointment in advance of placing the order or reporting the fault and then refer to the reserved appointment in the submitted order or fault.
So we added a way of describing parts of the anticipated order or fault report in the appointment search and reservation to explain the "skills" required.
So we would use something akin to product characteristics to say this is an install for a Product and the Product is based on FTTP and we want the premium service where the visiting technician will not just install FTTP but also fit the modem and perform a survey of the premises wifi and connect up some devices.
Then in addition to that there is of course the location (although for faults that is dealt with by reference to the product instance that needs repairing) and the timeframe for search or the time for reservation.
Everything else about the appointment (like site contact details, access arrangements and information about site hazards) is dealt with in the order or fault report which is submitted.
The only other thing is that we also have different grades of appointment for this.
So if you want assurance that the technician will turn up in a two hour window rather than five hour window we have a "type" of appointment which is standard or premium. We also have other types which will add slots outside of core working hours. All of these come at additional cost of course.
As for a report of the work conducted after the appointment is over I can see how that could be part of the appointing API.
In our model we deal with that separately as part of information about the completion of the order or repair of the fault.
------------------------------
Derrick Evans
BT Group plc
------------------------------
Original Message:
Sent: Feb 16, 2024 04:19
From: Ashutosh Mishra
Subject: Field API 646
Hi Lutz,
Thanks for your response, i have added my response below.
1. Arrange for a technician having the needed skills at a given place and find a time slot where he will be available.
[AM] yes in the current SearchTimeSlot we are not sure where we can pass this specific information regarding the skillset of the engineer. We are passing limited setof data into the GET/SearchTimeSLot for getting number of available slots based on appointment date which is like a @QueryParam not a payload actually so not sure how we can extend the same.
Possibly we can add the extension in POST/Appointment request , will give it a thought
2. When on site, the technician captures the described information and inserts it into some document, that you model as AttachmentRefOrValue.
[AM] The engineers on site will fill these questionnaire in case of successful or unsuccessful appointment into their handheld devices or smartphones so it not a document actually. We are then storing this data into Salesforce Field Management where we are actually managing appointment . And then as part of the milestone which are actually TMF646 Appointment State Change Events we are passing this information back to the upstream order management systems which is integrated with Salesforce FM. I'll check with team if we can try storing this data into document using Document API and then we can associated it on AttachmentRef.. this might be something we can explore if we dont have any relevant resources in 646.
Thanks!
------------------------------
Ashutosh Mishra
Tech Mahindra Limited
Original Message:
Sent: Feb 16, 2024 03:49
From: Lutz Bettge
Subject: Field API 646
Hi,
as I am currently working on upgrading the TMF646 (Appointment) from version 4 to version 5, I would like to better understand the scenario and how you plan to use this API. From my understanding, you are talking about two use cases:
- Arrange for a technician having the needed skills at a given place and find a time slot where he will be available.
I think this should be done by POSTing a SearchTimeSlot that includes the requestedTimeSlot; what is not so obvious is how one can express the needed skills; I imagine that the relatedParty might point to a PartyRole that does not have an engagedParty attached, which expresses that we know that we need a "technician", but do not yet know which person will take that role. The PartyRole would then have to point to the needed skills (that would be an extension of PartyRole, I assume), and based on that information a person (Party/Individual) can be identified that has the required skills and is available at the requested time and location to work on the relatedEntity, and then the relatedParty on the SearchTimeSlot would be changed to point to the identified person, with role="technician".
To enable this, you would either have to use PartyRole.characteristic as mentioned by Jonathan, or to extend PartyRole by Skill, similar to the Skill on Party. - When on site, the technician captures the described information and inserts it into some document, that you model as AttachmentRefOrValue.
In version 4, AttachmentRefOrValue has only limited capabilities to carry concrete information, the captured information could be captured as attachmentType and maybe description (as far as I understand it is not necessary to interpret Attachment as a document, could be some piece of information only), or you store the data in some document that you store via the Document API and refer to by AttachmentRef. The Document (managed by TMF667) can either be some binary file like a PDF or similar, or you can use its characteristics to store the captured data. The document could also be specified by a DocumentSpecification, and that defines via CharactersticSpecification which characteristics exist in that type of document.
Does this make sense?
Do we have to modify/extend anything in the Attachment API when we create the Version 5?
------------------------------
Lutz Bettge
Deutsche Telekom AG
Original Message:
Sent: Feb 15, 2024 08:33
From: Jonathan Goldberg
Subject: Field API 646
If you want to pass more structured data, as you show here, name-value pairs, one possibility would be to define the questionnaire as a collection of Characteristics. But we strongly recommend that Characteristics are not used in an unrestricted fashion - they should be backed by Characteristic Specifications.
Possibly other people might be able to give alternative recommendations?
Hope it helps
------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
Original Message:
Sent: Feb 15, 2024 07:04
From: Ashutosh Mishra
Subject: Field API 646
Hi Jonathan,
Thanks for the clarification earlier, i still have few doubts and I hope you can advice on this:
We have two type of data which we are trying to map in TMF646:
- Health and Safety skills used by SFS to select the right engineers to send to the site that requires them (some example below)
Skill Name | Skill ID | Answer |
S1 - Ladders leaning | HS1 | Yes/No |
S2 - Ladders vertical | HS2 | Yes/No |
S3 - Steps | HS3 | Yes/No |
S4 - Drills | HS4 | Yes/No |
S5 - Angle Grinders | HS5 | Yes/No |
- Questionnaire - Closure questionnaire presented to engineer upon marking the job as complete/incomplete. Sent to upstream in milestone notification or Questionnaires answered by the Field engineer's on site while doing the installation work as below
Question | Field name | answer format | answer options |
QC01 | Target Time | Date & Time format | System Defaulted |
QC02 | Task complete date & time | **/**/**** | Date & Time Format |
QC03 | Ring Ahead ? | Drop down | Yes |
QC05 | Service tested? | Drop down | Yes |
No |
QC06 | Why service not tested ? | Free Text | |
QC07 | Closure Notes | free Text | |
We want to pass this data to the upstream system which are used by Order management personal to keep a track of the appointment in case any changes are needed and some of the data also help them in passing information to other teams like configuration .
Not sure if we can use "AttachmentRefOrValue" object for this data set as this are mostly name/value pair kind of data?
At the moment there is no right placeholders available in 646 API for questionaire data, what do you recommend here - shall we make a simple extension of name value pair in existing API or use some object.
We want to align as much as possible with TMF API Standard but nit having right placeholders is what we are stuck with?
It would be really great if you can advise on the right way forward. I dont know if TMF already have any plans to enhance the API , may be someone else have also encountered similar issues.
I'll wait for your response, thanks in advance!
------------------------------
Ashutosh Mishra
Tech Mahindra Limited
Original Message:
Sent: Feb 12, 2024 10:05
From: Jonathan Goldberg
Subject: Field API 646
This would seem to be a correct usage, presumably the questionnaire will be a PDF, image scan, or word document, or similar?
Note the difference between ref and value - specifically for attachment:
- Ref means that the attachment details are created elsewhere as a persistent object and you just refer to it by foreign key (id)
- Value means that the attachment details are embedded within your API object and not created elsewhere
This is orthogonal to the location of the attachment contents (the PDF, word, image file), here you have mutually exclusive properties in the attachment details:
- content - is the actual content of the attachment, in Base64 encoding, embedded within the attachment details
- url - points to the content of the attachment in some document management system or content management system
Hope it is clear
------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
Original Message:
Sent: Feb 12, 2024 08:50
From: Ashutosh Mishra
Subject: Field API 646
Hi There,
Can anyone please advise where to capture the "Questionaire data" and "Site Safety" details in TMF API , in our implementation there are yes/no questionaire.
We were thinking to use "AttachmentRefOrValue" for capturing info , is that right place?
Questionnaire sample-
- any issues faced in installation (Yes/no)
- is site near secured area (yes/no)
Thanks in advance!
Regards
Ash
------------------------------
Ashutosh Mishra
Tech Mahindra Limited
------------------------------