UG Customer Onboarding Interface Guide

From CTMS

Aptean Logo.png







Aptean

Customer Onboarding Interface Guide

CTMS USER GUIDE - 11.47

16/02/24 - 1.0
Reference: UG-CUST-API











































This guide is intended to show the use and functionality of the customer onboarding webservice.


Basic webservice method

A webservice endpoint will be available similar to the following: 

http://{ip or domain or URL):{port}/orawsv/MTS_OWNER/DP_CTMS_IMPORT/IMPORT_CUSTOMER

Sample request: 

<soapenv:Envelope xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/ xmlns:imp=http://xmlns.oracle.com/orawsv/MTS_OWNER/DP_CTMS_IMPORT/IMPORT_CUSTOMER>
  <soapenv:Header/>
  <soapenv:Body>
     <imp:CXMLTYPE-IMPORT_CUSTOMERInput>
        <imp:CTMS_CUST-XMLTYPE-IN>
           <!—CONTENT -->
        </imp:CTMS_CUST-XMLTYPE-IN>
     </imp:CXMLTYPE-IMPORT_CUSTOMERInput>
  </soapenv:Body>
</soapenv:Envelope>


Sample Response: 

<soap:Envelope xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/>
  <soap:Body>
     <IMPORT_CUSTOMEROutput xmlns=http://xmlns.oracle.com/orawsv/MTS_OWNER/DP_CTMS_IMPORT/IMPORT_CUSTOMER>
        <RETURN>
           <CTMS_IMPORT_CUSTOMER_RESPONSE RESULT="NAK"> 
              <RESULTS>
                 <RESULT>
                    <CUSTOMER_ID></CUSTOMER_ID>
                    <STATUS></STATUS><!—SUCCESS|INVALID|FAILED-->
                    <STATUS_MSG>Some success or failure text</STATUS_MSG>
                 </RESULT>
                 <RESULT>
                    <LOCATION_ID></LOCATION_ID>
                    <EXT_REF></EXT_REF>
                    <STATUS></STATUS><!—SUCCESS|INVALID|FAILED-->
                    <STATUS_MSG>Some success or failure text</STATUS_MSG>
                 </RESULT>
              </RESULTS>
           </CTMS_IMPORT_CUSTOMER_RESPONSE>
        </RETURN>
     </IMPORT_CUSTOMEROutput>
  </soap:Body>
</soap:Envelope>


Configuration

An API (import) process must be configured in CTMS.

Import process parameters supported by this webservice method:

  • LOC_LOADING_RATE - default if not provided
  • LOC_UNLOADING_RATE - default if not provided
  • LOC_DEPOT - default if not provided
  • LOC_FLEXIPOD - default if not provided
  • DEFAULT_COST_CENTRE - default if not provided
  • CUST_EPOD_ENABLED - default if not provided
  • INSPECT_PERIOD_TYPE - default if not provided
  • INSPECT_PERIOD_VALUE - default if not provided
  • INSPECT_DATE_FROM - default if not provided
  • CUST_TYPE - default if not provided
  • CUST_REV_CHARGE_TYPE - default if not provided
  • CUST_LOTS_ID - Y or N - whether the customer created will interface events to Aptean Calidus TMS Portal TTM (Track and Trace Module)
  • CUST_CURRENCY - default if not provided
  • CUST_GROUP_CUSTOMER - Y or N - create a customer associated to the Customer Group provided.
  • AUDIT_STATUS - which statuses to audit from the received messages. Values: ALL (default), or a combination of NAK, WAK, ACK.
  • AUDIT_METHOD - how to audit messages. Values: WS (default), NONE, FILE
  • CUST_LOTS_SEND_ORD - Y or N - if Y, set the customer so that it sends ORD messages to Portal TTM.
  • UPDATE_PARAGON_ID - Y or N - if Y, set the Paragon ID to {Customer ID}_{EXT_REF}


Interface Import Decode for type "LOC_DEPOT":

  • "BILLING" – "HO"

This table allows for configuration of location types provided in the interface to Aptean CTMS location types.

Content Format

Content is XML.

Customer Section

This is the main section - only 1 CUSTOMER tag may be sent per message.

This is the details of the customer being created.

Once processed, the system will have created the following:

  • Customer record
  • Group for the customer
  • Financial Account record
  • Invoicing Requirements
  • Shared Currency

Fields allowed within the CUSTOMER tag are:

Field Size Default Req Notes
CUSTOMER_ID VARCHAR2(12) Y Must be provided
CUSTOMER_NAME VARCHAR2(50) Y Must be provided
CONTACT_NAME VARCHAR2(50) O
CUST_GROUP VARCHAR2(12) O If provided, a customer group will be created if it does not exist. If provided, a customer group must exist. If configured, the system will create the customer group from an identified customer (i.e. parent customer). If neither, an error is raised.
COST_CENTRE_NAME VARCHAR2(12) O If not provided and a default exists, defaults to that value. If a default does not exist, raises an errorthis is left blank
VAT_COUNTRY VARCHAR2(3) O If provided, must exist
VAT_REG_NO VARCHAR2(50) O
COUNTRY VARCHAR2(3) Y REQUIRED, MUST EXIST
TYPE VARCHAR2(12) "CUSTOMER" O If not provided and a default exists, defaults to that value. If a default does not exist, raises an error
ORDER_REVENUE_CHARGING_TYPE_ID NUMBER 6 If not provided and a default exists, defaults to that value. If a default does not exist, raises an error
STD_INSTR VARCHAR2(4000) O Any standard instructions for the customer
FREE_TEXT1 VARCHAR2(255) O
FREE_TEXT2 VARCHAR2(255) O
FREE_TEXT3 VARCHAR2(255) O
FREE_TEXT4 VARCHAR2(255) O
FREE_TEXT5 VARCHAR2(255) O
ACCOUNT_ON_HOLD VARCHAR2(1) "N" O Will default if not provided.
ACC_CURRENCY_USAGE VARCHAR2(3) O If not provided and a default exists, defaults to that value. If a default does not exist, raises an error
ACCOUNT_TYPE VARCHAR2(30) O
PAY_ON_DELIVERY VARCHAR2(1) O "N" - Not forced payment, "C" - cash only, "Y" - any (cash/cheque/card)
COLLECT_CASINGS VARCHAR2(1) O
NETWORK_AVAILABLE VARCHAR2(1) O
GEO_LOCATIONS O Subsection below


Location Section

The locations section describes locations that are to be created that belong to that customer. This can be delivery locations, head office locations, invoice addresses, or any other location type configured in Aptean CTMS.

Sub-section GEO_LOCATIONS is populated with a list of GEO_LOCATION tags, populated as follows:

Field Size Default Req Notes
LOCATION_ID VARCHAR2(12) O This or EXT_REF must be provided. See notes.
DEPOT VARCHAR2(12) "BRANCH" O If not provided and a default exists, defaults to that value. If a default does not exist, raises an error
LOCATION_NAME VARCHAR2(50) Y
EXT_REF VARCHAR2(50) O This or LOCATION_ID must be provided. See notes.
ADDRESS_LINE1 VARCHAR2(50) Y
ADDRESS_LINE2 VARCHAR2(50) O
ADDRESS_LINE3 VARCHAR2(50) O
TOWN VARCHAR2(50) O
COUNTY VARCHAR2(50) O
COUNTRY_CODE VARCHAR2(3) Y Must exist
POSTCODE VARCHAR2(9) Y Must be provided, not blank
PHONE VARCHAR2(50) O
FAX VARCHAR2(50) O
LOADING_RATE VARCHAR2(12) "DEFAULT" O If not provided and a default exists, defaults to that value. If a default does not exist, raises an error. Note that, if the location already exists and has rate already set against it, and this rate is not provided in the message, the rate will not be overwritten by the default value parameter.
UNLOADING_RATE VARCHAR2(12) "DEFAULT" O If not provided and a default exists, defaults to that value. If a default does not exist, raises an error. Note that, if the location already exists and has rate already set against it, and this rate is not provided in the message, the rate will not be overwritten by the default value parameter.
RESPONSIBLE_COST_CENTRE VARCHAR2(50) O If not provided and a default exists, defaults to that value. If a default does not exist, raises an error.
COST_CENTRE_NAME VARCHAR2(12) O If not provided and a default exists, defaults to that value. If a default does not exist, raises an error.
EXT_LOCATION_NAME VARCHAR2(50) O External Location Name
COMMENTS VARCHAR2(255) O
GEO_LOCATION_USAGE O Subsection below
GEO_CONTACTS O Subsection below
GEO_LOCATION_WINDOWS O Subsection below

Note: A failure to process this section will not cause a failure of the customer or the entire message - the customer will still be added. The response will indicate if there is any issue in creating these details as a warning.


Location Usage Section

This section defines how the locations are owned within the system.

This section is optional - if omitted, the process will use the system defaults for location usage.

Sub-section GEO_LOCATION_USAGE is populated as follows:

Field Size Default Req Notes
USAGE_TYPE VARCHAR2(12) "CUSTOMER" O If provided, validated as a valid value. Valid values "CUSTOMER", "CUSTOMER_GROUP". If not provided, defaults to "CUSTOMER"
USAGE_ID VARCHAR2(12) Y Set to customer ID or Customer Group

Note: A failure to process this section will not cause a failure of the location or the entire message - the customer and location will still be added. The response will indicate if there is any issue in creating these details as a warning.


Contacts Section

This section defines the location contacts.

This section is optional.

Sub-section GEO_CONTACTS is populated with a list of GEO_CONTACT tags, populated as follows:

Field Size Default Req Notes
SURNAME VARCHAR2(50) O SURNAME or FORENAME must be provided.
FORENAME VARCHAR2(50) O SURNAME or FORENAME must be provided
JOB_TITLE VARCHAR2(50) O
PHONE VARCHAR2(50) O
EMAIL VARCHAR2(100) O
TITLE VARCHAR2(12) O

Note: A failure to process this section will not cause a failure of the location or the entire message - the customer and location will still be added. The response will indicate if there is any issue in creating these details as a warning.


Location Windows Section

This section defines location opening times per day.

This section is optional - if not provided, the location is assumed to be open on all days.

Sub-section GEO_LOCATION_WINDOWS is populated with a list of GEO_LOCATION_WINDOW tags, populated as follows:

Field Size Default Req Notes
DAY NUMBER Y 1-7 where 1 is Sunday
OPENING_TIME NUMBER Y
CLOSING_TIME NUMBER Y

Note: A failure to process this section will not cause a failure of the location or the entire message - the customer and location will still be added. The response will indicate if there is any issue in creating these details as a warning.


Sample XML structure

<?xml version="1.0" encoding="UTF-8"?>
<CALIDUS_XML>
<EVENT>
<EVENT_HEADER>
   <EVENT_PROCESSED>N</EVENT_PROCESSED>
   <EVENT_SOURCE_TYPE>CDE</EVENT_SOURCE_TYPE>
   <EVENT_SOURCE_NAME>SYSTEM</EVENT_SOURCE_NAME>
   <EVENT_DATE>2021-07-21T08:20:28</EVENT_DATE>
   <EVENT_TYPE>CUST</EVENT_TYPE>
   <EVENT_ACTION>C</EVENT_ACTION>
</EVENT_HEADER>
<EVENT_DETAIL>
 <CUSTOMER>
   <CUSTOMER_ID></CUSTOMER_ID>
   <CUSTOMER_NAME></CUSTOMER_NAME>
   <CONTACT_NAME></CONTACT_NAME>
   <CUST_GROUP></CUST_GROUP>
   <COST_CENTRE_NAME></COST_CENTRE_NAME>
   <VAT_COUNTRY></VAT_COUNTRY>
   <VAT_REG_NO></VAT_REG_NO>
   <COUNTRY></COUNTRY>
   <TYPE></TYPE>
   <ORDER_REVENUE_CHARGING_TYPE_ID></ORDER_REVENUE_CHARGING_TYPE_ID>
   <STD_INSTR></STD_INSTR>
   <FREE_TEXT1></FREE_TEXT1>
   <FREE_TEXT2></FREE_TEXT2>
   <FREE_TEXT3></FREE_TEXT3>
   <FREE_TEXT4></FREE_TEXT4>
   <FREE_TEXT5></FREE_TEXT5>
   <ACCOUNT_ON_HOLD></ACCOUNT_ON_HOLD>
   <ACC_CURRENCY_USAGE></ACC_CURRENCY_USAGE>
	<ACCOUNT_TYPE></ACCOUNT_TYPE>
	<PAY_ON_DELIVERY></PAY_ON_DELIVERY>
	<COLLECT_CASINGS></COLLECT_CASINGS>
	<NETWORK_AVAILABLE></NETWORK_AVAILABLE>
	<GEO_LOCATIONS>
		<GEO_LOCATION>
			<LOCATION_ID></LOCATION_ID>
			<DEPOT></DEPOT>
			<LOCATION_NAME></LOCATION_NAME>
			<EXT_REF></EXT_REF>
			<ADDRESS_LINE1></ADDRESS_LINE1>
			<ADDRESS_LINE2></ADDRESS_LINE2>
			<ADDRESS_LINE3></ADDRESS_LINE3>
			<TOWN></TOWN>
			<COUNTY></COUNTY>
			<COUNTRY_CODE></COUNTRY_CODE>
			<POSTCODE></POSTCODE>
			<PHONE></PHONE>
			<FAX></FAX>
			<LOADING_RATE></LOADING_RATE>
			<UNLOADING_RATE></UNLOADING_RATE>
			<RESPONSIBLE_COST_CENTRE></RESPONSIBLE_COST_CENTRE>
			<COST_CENTRE_NAME></COST_CENTRE_NAME>
			<EXT_LOCATION_NAME></EXT_LOCATION_NAME>
			<COMMENTS></COMMENTS>
			<GEO_LOCATION_USAGE>
				<USAGE_TYPE></USAGE_TYPE>
				<USAGE_ID></USAGE_ID>
			</GEO_LOCATION_USAGE>
			<GEO_CONTACTS>
				<GEO_CONTACT>
					<SURNAME></SURNAME>
					<FORENAME></FORENAME>
					<JOB_TITLE></JOB_TITLE>
					<PHONE></PHONE>
					<EMAIL></EMAIL>
					<TITLE></TITLE>
				</GEO_CONTACT>
				<GEO_CONTACT>
					<SURNAME></SURNAME>
					<FORENAME></FORENAME>
					<JOB_TITLE></JOB_TITLE>
					<PHONE></PHONE>
					<EMAIL></EMAIL>
					<TITLE></TITLE>
				</GEO_CONTACT>
			</GEO_CONTACTS>
			<GEO_LOCATION_WINDOWS>
				<GEO_LOCATION_WINDOW>
					<DAY></DAY>
					<OPENING_TIME></OPENING_TIME>
					<CLOSING_TIME></CLOSING_TIME>
				</GEO_LOCATION_WINDOW>
				<GEO_LOCATION_WINDOW>
					<DAY></DAY>
					<OPENING_TIME></OPENING_TIME>
					<CLOSING_TIME></CLOSING_TIME>
				</GEO_LOCATION_WINDOW>
			</GEO_LOCATION_WINDOWS>
		  </GEO_LOCATION>
		<GEO_LOCATION>
			<LOCATION_ID></LOCATION_ID>
			<DEPOT></DEPOT>
			<LOCATION_NAME></LOCATION_NAME>
			<EXT_REF></EXT_REF>
			<ADDRESS_LINE1></ADDRESS_LINE1>
			<ADDRESS_LINE2></ADDRESS_LINE2>
			<ADDRESS_LINE3></ADDRESS_LINE3>
			<TOWN></TOWN>
			<COUNTY></COUNTY>
			<COUNTRY_CODE></COUNTRY_CODE>
			<POSTCODE></POSTCODE>
			<PHONE></PHONE>
			<FAX></FAX>
			<LOADING_RATE></LOADING_RATE>
			<UNLOADING_RATE></UNLOADING_RATE>
			<RESPONSIBLE_COST_CENTRE></RESPONSIBLE_COST_CENTRE>
			<COST_CENTRE_NAME></COST_CENTRE_NAME>
			<EXT_LOCATION_NAME></EXT_LOCATION_NAME>
			<COMMENTS></COMMENTS>
			<GEO_LOCATION_USAGE>
				<USAGE_TYPE></USAGE_TYPE>
				<USAGE_ID></USAGE_ID>
			</GEO_LOCATION_USAGE>
			<GEO_LOCATION_WINDOWS>
				<GEO_LOCATION_WINDOW>
					<DAY></DAY>
					<OPENING_TIME></OPENING_TIME>
					<CLOSING_TIME></CLOSING_TIME>
				</GEO_LOCATION_WINDOW>
				<GEO_LOCATION_WINDOW>
					<DAY></DAY>
					<OPENING_TIME></OPENING_TIME>
					<CLOSING_TIME></CLOSING_TIME>
				</GEO_LOCATION_WINDOW>
			</GEO_LOCATION_WINDOWS>
		  </GEO_LOCATION>
	</GEO_LOCATIONS>
 </CUSTOMER>
</EVENT_DETAIL>
</EVENT>
</CALIDUS_XML>


General Notes

  • Customer ID is 12 characters and cannot be increased
  • The type is "CUSTOMER" but can be configured to default to this.
  • The cost centre can be defaulted.
  • The order revenue charging type ID can be defaulted.
  • The currency usage will be defaulted to "GBP" unless provided.
  • The "HO" address provided for a customer will be identified as the home address and the customer will be updated with that address.
  • LOCATION_ID or EXT_REF must be provided. If this is not, the file will be rejected. The value of LOCATION_ID provided will be used in preference to EXT_REF and used to retrieve the location if it already exists. If LOCATION_ID is not provided, EXT_REF will be used to retrieve the location if it already exists. Either LOCATION_ID or EXT_REF must uniquely identify a location.


Responses

Sample Response: 

<soap:Envelope xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/>
  <soap:Body>
     <IMPORT_CUSTOMEROutput xmlns=http://xmlns.oracle.com/orawsv/MTS_OWNER/DP_CTMS_IMPORT/IMPORT_CUSTOMER>
        <RETURN>
           <CTMS_IMPORT_CUSTOMER_RESPONSE RESULT="NAK"> 
              <RESULTS>
                 <RESULT>
                    <CUSTOMER_ID></CUSTOMER_ID>
                    <STATUS></STATUS><!—SUCCESS|INVALID|FAILED-->
                    <STATUS_MSG>Some success or failure text</STATUS_MSG>
                 </RESULT>
                 <RESULT>
                    <LOCATION_ID></LOCATION_ID>
                    <EXT_REF></EXT_REF>
                    <STATUS></STATUS><!—SUCCESS|INVALID|FAILED-->
                    <STATUS_MSG>Some success or failure text</STATUS_MSG>
                 </RESULT>
              </RESULTS>
           </CTMS_IMPORT_CUSTOMER_RESPONSE>
        </RETURN>
     </IMPORT_CUSTOMEROutput>
  </soap:Body>
</soap:Envelope>


A CTMS_IMPORT_CUSTOMER_RESPONSE tag will include a RSULT indicator, showing the basic status of the message:

  • ACK - Acknowledged, processed successfully.
  • WAK - Warning, but Acknowledged, partially processed.
  • NAK - Not acknowledged - for failed/invalid, not processed at all.

A RESULT section will be included for the Customer and each location that was provided in the interface.

A status and status message will be included in each RESULT section, along with primary and secondary key values, for alignment by the sending system.

Note Note: This is not an exhaustive list, simply indicative of the types of responses that may be received.

RESULT attribute STATUS tag STATUS_MSG tag
ACK SUCCESS Customer created.
ACK SUCCESS Customer updated.
NAK INVALID Customer not created – X not provided (where X is the field not provided)
NAK INVALID Customer not created – X not provided (no default exists). (where X is the field not provided)
NAK FAILED Customer not created – database failure (X) (where X is the database error message)
NAK FAILED Customer not created – Customer Group X does not exist (where X is the provided customer group)
ACK SUCCESS Location created.
ACK SUCCESS Location updated.
WAK INVALID Location not created – X not provided. (where X is the field not provided)
WAK INVALID Location not created – X not provided (no default exists). (where X is the field not provided)
WAK FAILED Location not created – database failure (X) (where X is the database error message)
WAK INVALID Location not created – Neither location nor external reference provided
WAK FAILED Location usage not created (appended to Location created/updated message).
WAK SUCCESS Some contacts have not been created. (appended to Location created/updated message).
WAK SUCCESS Some windows have not been created. (appended to Location created/updated message).
Retrieved from ‘https://calidusassist.adcservices.apteancloud.com/calidus-assist/MTS/index.php?title=UG_Customer_Onboarding_Interface_Guide&oldid=6388’