InnerWeb
Skip to main content

Delivery appointment SOAP integration: implementation notes

Fetching delivery data by card code works over SOAP and requires implementation work on both sides. The customer's IT team and the appointment system vendor should agree a few things before go-live: the key, the set of fields, the behaviour for unknown codes and access to telemetry.

5
stages of the integration rollout
Source: implementation recommendation
5 characters
canonical visit card code
Source: delivery functions sheet

Scope of the integration and what we do not promise

After a visit card code is entered, the Deliveries and appointments module in InnerWeb fetches the planned delivery data from the customer's appointment system and pre-fills the form. The integration runs over SOAP. We do not promise integration with any appointment system without implementation work, because each system has its own fields, limits and way of returning data.

InnerWeb is an independent system that complements the customer's existing systems. The appointment system remains the source of the delivery plan, while our side is responsible for consuming the data and for the behaviour at the gate.

Implementation stages in order

The order of work matters, because many problems only show up at the gate, when a driver is waiting. We recommend five stages.

  • Stage 1: agree the SOAP service contract, meaning the input and output fields
  • Stage 2: technical access and a test environment on the appointment system side
  • Stage 3: mapping of appointment fields to delivery fields in InnerWeb
  • Stage 4: tests on real codes, non-existent codes and deliveries already completed
  • Stage 5: a trial run at one gate with telemetry of lookups switched on

Sample share of work across integration stages (example calculation)

Sample share of work across integration stages (example calculation)Bar chart: contract 15 percent, access 15, mapping 25, tests 30, trial run 150102030%SOAP contract: 15 %15 %SOAP contractAccess and environment: 15 %15 %Access andenvironmentField mapping: 25 %25 %Field mappingTests: 30 %30 %TestsTrial run: 15 %15 %Trial run
Source: Example calculation: an assumed split of work, not client data

Agreements without which the integration will not work

It is best to write the points below into an agreement protocol and sign it on both sides before the first test starts.

Linking key and code format

The visit card code is a separate field of the delivery and serves as the key linking the delivery in InnerWeb to the record in the customer's appointment system. The lookup goes out with one canonical five-character code, and leading zeros typed by security do not change the result. The appointment system vendor must confirm that this format matches its codes.

Behaviour for unknown codes and completed transports

The external system can return the last completed transport for unknown codes. That is why a delivery with a completed transport in the appointment system is deliberately treated as missing data, so that the driver is not wrongly identified and no GDPR problem arises. The vendor should describe how its service responds to an unknown code, and the customer's IT team should confirm it with a test.

Mandatory fields and gaps

The operation type from the appointment sets the delivery label, and the service point name is matched against the gate and dock codes. When an appointment has no carrier, the system inserts a placeholder carrier. It is worth agreeing which appointment fields are mandatory on the vendor's side, so that a missing carrier does not become the norm.

Common pitfalls of the rollout

The first pitfall is a mismatch between service point names and dock codes in InnerWeb. Matching is done by name, so a difference in spelling means a delivery without an assigned warehouse. Dictionaries must be aligned before the tests.

The second pitfall is the response time of the service. Security will not wait for a response that takes many seconds at the gate. Telemetry records the response time of every lookup, so the acceptable limits should be set before go-live, based on the data from the tests.

The third pitfall is the maintenance windows of the appointment system. If the service is unavailable at night while the plant works around the clock, security needs a procedure for creating the delivery by hand, because no answer from the system means no data.

Telemetry as part of the agreements

Every lookup by visit card code is recorded in telemetry: the code, the result, the status, the response time and the source. It is worth agreeing with the vendor from the start that these records will be the basis for discussing reports about inactive cards. A dispute about who is right then ends with numbers.

Data protection also belongs in the agreements: who sees the card codes, how long we keep the records and who may ask to see them. The arrangements should be checked with the customer's data protection officer.

Video

Frequently asked questions

Is the integration with the appointment system ready out of the box?

No. The integration runs over SOAP and requires implementation work on both sides. We do not promise integration with any appointment system without it.

What happens to a delivery whose transport was completed in the appointment system?

It is deliberately treated as missing data, because the external system may return the last completed transport for unknown codes, which would risk wrongly identifying the driver.

What should security do when the appointment service is unavailable?

Create the delivery by hand according to the prepared procedure. No answer from the system is treated as missing data.

Sources

Let's plan the integration with your appointment system

Book a call with our team. Together with your IT department and the appointment system vendor, we will write down the contract and the stages of work.

Let's talk