Provider API for Dock Appointment Scheduling
As a shipper, you can use this inbound service to create dock appointment requests and confirmed dock appointments in SAP Business Network for Logistics based on the information from your external systems such as a transportation system, warehouse management system, yard management system and so on. You can also use this service to provide a guest user access to your customers and carriers who are not on SAP Business Network for Logistics and enable them to maintain the appointment details.
Technical Name
GenericAppointment_In
Description
In general, you can create or update appointment requests with this API. In addition to that, you can create or update booked appointments with this API. You can also update appointment requests to booked appointments.
-
Appointment requests are not yet scheduled appointments. They are assigned to a docking location and optionally also to a loading point but not to a time slot. Thus, they do not consume capacity on a loading point. Appointment requests have the appointment status as 01.
-
Booked appointments are scheduled appointments, which means they have been assigned to a time slot on a certain loading point and consume its capacity. Booked appointments have the appointment status as 03.
Appointment requests can be changed to booked appointments either via this API or via the shipper UI (Manage Dock Appointments app) or the carrier UI (Self- Book Dock Appointments app) by assigning a time slot on a certain loading point to them.
In more detail, you can perform the following in SAP Business Network for Logistics using this API:
-
Create an appointment request
Note that to create an appointment request, you must send the appointment status as 01 from your external system to the network. You might want to provide a new appointment external ID at this point. The corresponding appointment ID for the new appointment request is generated in the system.
-
Book an appointment
Note that to book an appointment, you must send the appointment status as 03 (or 02) and the appointment key from your external system to the network.
-
Update an appointment request
Note that to update an appointment request, you must send the appointment status as 01 and the appointment key from your external system to the network.
-
Update a booked appointment
Note that to update a booked appointment, you must send the appointment status as 03 and the appointment key from your external system to the network.
Prerequisites
You have performed the following:
-
You have created a shipper and carrier business partner in your SAP Business Network for Logistics and your external system.
-
In your external system, you have the LBN ID and you have mapped the LBN ID with the business partner.
-
You have created the location master data and corresponding loading point and docking location in SAP Business Network for Logistics. You must use this location ID and loading point ID in the webservice SOA Manager interface.
Appointment Key
Appointments can be uniquely identified by a combination of the sender system ID and the appointment external ID that was used to create them, or by the appointment ID. The appointment ID is generated as a consecutive number during the creation of an appointment within the network, and it is shown in the UI.
Structure
They system has different fields categorized under different nodes. Each node contains various fields. Below are some of the important fields displayed by the system:
Technical Name | Field | Description | Node |
---|---|---|---|
OrderingPartyLbnId | Ordering Party LBN ID* | Contains the ordering party ID maintained in SAP Business Network for Logistics | Appointment |
CarrierLbnId | Carrier LBN ID* | Contains the carrier ID maintained in SAP Business Network for Logistics | Appointment |
SenderSystemId | Sender System ID* |
Contains the ID of sender system (see also AppointmentExternalId) |
Appointments |
AppointmentId | Appointment ID | A consecutive number that serves as a key for the appointment. It is sent back to the caller via GenericAppointment_Out after the creation of an appointment in the network. | Appointment |
AppointmentStatusCode | Appointment Status Code |
Contains one of the following status codes: 01 – Appointment Request Created 02 – Pending Confirmation 03 – Confirmed |
Appointments |
AppointmentExternalId | Appointment External ID | An externally provided key for the appointment. It is provided during creation and then used during update operations. The key is unique in combination with the sender system ID. | Appointment |
DockingLocationId | Docking Location ID* |
Represents the location ID assigned to a docking loaction in the Manage Entities app. Example: QM7_910:LBN_WDF (<SourceSystem>:<ExternalID>) For more information about locations, see: Viewing a Location. |
Appointment |
LoadingPointId | Loading Point ID |
Represents the loading point ID defined in the Manage Entities app (for example: Loading_Point_ID_1). This field is not required for appointment request creation but is required when creating a booked appointment. If the loading point ID is provided already for the appointment request, it cannot be changed anymore during appointment booking via the shipper or carrier UI. However, it still can be changed by the current API. |
Appointment |
LoadingActivityType | Loading Activity Type |
Contains one of the following activity types: 01 – Loading 02 – Unloading 03 – Loading/Unloading |
Appointments |
RequestedStartDateTime | Requested Start Date Time |
If an appointment is booked via this API with status 02 (Pending Confirmation), this field is used for the determination of the booked timeslot. If an appointment request with status 01 (Appointment Request Created) is created via this API, the requested dates are used to determine the planned dates. |
Appointment |
RequestedEndDateTime | Requested End Date Time |
If an appointment is booked via this API with status 02 (Pending Confirmation), this field is used for the determination of the booked timeslot. If an appointment request with status 01 (Appointment Request Created) is created via this API, the requested dates are used to determine the planned dates. |
Appointment |
AcceptableStartDateTime | Acceptable Start Date Time |
Acceptable time period corresponds to a broader horizon and overwrites the Enable Appointment Date Change setting for carriers in the Manage Entities app. This enables carriers to change the date of a dock appointment in the given acceptable time range before the cut-off time for carrier is reached. |
Appointment |
AcceptableEndDateTime | Acceptable End Date Time |
Acceptable time period corresponds to a broader horizon and overwrites the Enable Appointment Date Change setting for carriers in the Manage Entities app. This enables carriers to change the date of a dock appointment in the given acceptable time range before the cut-off time for carriers is reached. |
Appointment |
AppointmentStartDateTime | Appointment Start Date Time | Used for the determination of the booked time slot in combination with appointment status 03. | Appointment |
AppointmentEndDateTime | Appointment End Date Time | Used for the determination of the booked time slot in combination with appointment status 03. | Appointment |
DocumentId | Document ID | Contains the document ID of the source business document from your external system (For example, freight order, transport unit, yard order). | Appointment Reference Document |
CargoItemDescription | Cargo Item Description | Contains the cargo item description | Appointment Cargo Item |
DangerousGoodsAreContained | Dangerous Goods Are Contained | Contains the information whether dangerous goods are contained | Appointment Cargo Item |
CreatedAt | Created At | Contains the date and time at which the note was created | Appointment Note |
DocumentType | Document Type |
Contains one of the following types of reference documents: 001 – Purchase Order 58 – Inbound Delivery 73 – Outbound Delivery 111– Freight Request for Quotation 114 – Sales Order 612 – Shipment Order 614 – Freight Order 1122 – Transportation Order (Transportation Management) 1311 – Transportation Unit Appointment (Extended Warehouse Management) YO – Yard Order (Yard Logistics) |
Appointment Reference Document |
Note that the fields marked with * are mandatory fields.
Confirmed
If you book an appointment with status 03 (Confirmed), the system tries to book an appointment for the time slot that is defined by the appointment start date time and the appointment end date time. If this succeeds, a booked appointment with status 03 is created. Otherwise, the booking fails.
Pending Confirmation
If you book an appointment with status 02 (Pending Confirmation), the system tries to book an appointment for the time slot that is defined by the requested start date time and the requested end date time. If this succeeds, a booked appointment with status 03 is created. If it fails due to missing capacity, only an appointment request with status 01 is created.
Guest User Access
You can provide a guest user access to your customers and carriers who are not on SAP Business Network for Logistics and enable them to maintain the appointment details in SAP Business Network for Logistics system.
Once you provide a guest user access, the system generates an URL and sends it to the carrier in an email. To validate the authenticity of the accessing personnel, when the carrier navigates to the URL, the system prompts the carrier to enter additional appointment information such as the order number or delivery ID of the appointment. Once the carrier passes the security validation, the carrier can view the appointment details, select the time slots, and save the appointment. The customer can also invite a carrier to access this appointment and select the time slots.
The appointments which allow guest user access must contain the following:
-
Additional customer contact details such as the email address
-
Appointment type as EX
-
Role code as LBN_02
-
Document reference type as shown in the table under Structure for DocumentType.
-
The standard IDs of the SenderParty and RecipientParty header fields must be set to your own LBN ID.
You must also retrieve the email address of the customer from the business partner directory in your external system and pass the information through this service.
Create an Appointment Without Reference Document
The system enables you to create an appointment without a reference document. You can later add the details such as reference document details, order details, delivery ID, and so on. You can also add additional reference document details or replace a reference document.
Enable Overbooking
When you enable overbooking for a loading point, you can create multiple appointments or block a time slot multiple times irrespective of the capacity of the loading point. You can also enable overbooking only for a carrier or only for you as a shipper depending on your settings for that loading point.
In the appointment confirmation, a new node has been added for messages. You can view the messages in the following scenarios:
-
If a customer creates an appointment via API, the system creates a confirmation message for the same.
-
If the loading point is not set for overbooking and if preferred time slot is not available, the system does not create the appointment and creates an error message for the same.
-
When the customer sends the appointment with the status as Pending Confirmation and the system changes the appointment status to either Confirmed or Appointment Request Created, the system provides a message for the same.
Preferred Slots / Slots Preferred by Shipper
When you maintain an appointment, the system displays the requested and acceptable dates for slot booking based on the following criteria:
-
The requested dates are taken from the RequestedStartDateTime and RequestedEndDateTime fields.
-
The acceptable dates are taken from the AcceptableStartDateTime and AcceptableEndDateTime fields.
Notes and Attachments
You can use this inbound API to update the SAP Business Network for Logistics system with the notes and attachments from your external systems.
The attachment name must contain the file extension. Example: Attachment.pdf.
Automatic Cancellation of Appointments
An appointment is automatically canceled if one of the following is changed:
-
Loading point
-
Docking location
-
Acceptable dates (start or end date)
-
Requested dates (start or end date)
The following exceptions apply:
-
If the changed requested dates match the start and end date of the scheduled appointment, the appointment will not be canceled.
-
If the start and end date of the scheduled appointment is within the range of the new acceptable start and end date, the appointment will also not be canceled.