API - Intermediary Service
Overview
The Sequoia API Intermediary Service is a service that extends the interoperability with the Sequoia API. This service provides a marshalling mechanism between multiple data exchange mechanisms and the Sequoia API on which this service depends.
A data exchange mechanism in this context is a process by which data can be exchanged between an external application and Sequoia without a direct connection to the Sequoia web services API. An example of this is where an external application writes data to a shared folder and Sequoia collects it from there and processes it.
Data exchange mechanisms are loaded as plug-ins via configuration. Each mechanism will have its own set of configurations.
All data exchange mechanisms will pass standard XML messages as defined in the Sequoia API documentation to the Intermediary service. Requests, responses and unsolicited messages will be wrapped in an XML envelope that has meta data attributes to describe the action being performed.
Technical Overview
The Sequoia API Intermediary Service can be hosted as a Windows service and should have free communication access to the Sequoia API and the chosen input mechanism(s) that it is configured to use. As such will need to be run under a user account that can access the configured data exchange mechanism(s).
Figure 1 - Intermediary Service Context By default, the intermediary service is configured to communicate with the Sequoia API service via SOAP over HTTP. If you are using a version of windows with UAC (User Account Control), you will have to make a namespace reservation using the following syntax at a command prompt which has been run with elevated privileges:
netsh http add urlacl url=http://+:<PORT>/Asm/Sequoia/SequoiaApiService user=<USERNAME>
Where
If you have a firewall running, it should be configured to allow access for the SequoiaApiService.
Communication to the API service is detailed in this document. In summary, the web methods accept XML formatted parameters and return XML data.
The XSD schema files used to validate this XML for both requests and responses are available as a request from the API service. They are detailed in the Sequoia API documentation and are also copied out to the Sequoia installation folder.
Configuration
The intermediary service should not require any additional configuration to communicate with the Sequoia API service assuming the API service configuration has not been modified.
System service model settings in the ASM.Sequoia.Api.IntermediaryService.exe.config file, by default, are set to use external configuration files.
Setting the Sequoia API Endpoint
If changes are required, open the WcfServiceClients.config file located in the API Intermediary service directory.
Locate the endpoint which has the name WSDualHttpBinding_ISequoiaApiService. Example below:
<endpoint address="http://SequoiaServer:9001/Asm/Sequoia/SequoiaApiService"
binding="wsDualHttpBinding"
bindingConfiguration="WSDualHttpBinding_ISequoiaApiService"
contract="ASM.Sequoia.Api.Contracts.ServiceContracts.ISequoiaApiDualChannelService"
name="WSDualHttpBinding_ISequoiaApiService" />
The endpoint value set should correspond to the values that the Sequoia API service has been configured to run on. Multiple endpoints can be defined although only one will be used at a time.
Setting the endpoint name and authentication
The user used for authentication to the API Service needs to be created using the Sequoia Management console as a non-Windows user and a password needs to be set.
Locate the following section within the 'ASM.Sequoia.Api.IntermediaryService.exe.config' file and set the userName and password values accordingly.
<!-- Intermediary Service Configuration -->
<ApiIntermediaryService endpointConfigurationName="WSDualHttpBinding_ISequoiaApiService" userName="user" password="password"/>
Message Envelopes
Intermediary Service Message Envelope
All messages sent to the Intermediary service need to be encapsulated in an XML envelope.
Request Message Envelope
<?xml version="1.0" encoding="utf-16"?>
<ApiRequestMessage>
<Action>GetAgentInventoryRecord</Action>
<CorrelationId>0000000003</CorrelationId>
<PayLoad>
</PayLoad>
</ApiRequestMessage>
| Attribute Name | Description |
|---|---|
| Action | Specifies the method to be executed on the Sequoia API. |
| CorrelationId | A string that can be used to match responses with requests. The response received from the Sequoia API will have a corresponding attribute with this value. |
| Payload | The content that needs to be sent to the Sequoia API when the method specified in 'Action' is invoked. |
Response Message Envelope
<?xml version="1.0"?>
<FormattedResponseApiData xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<CorrelationId>0000000001</CorrelationId>
<ResponseDateTime>2019-03-18T14:20:09.5658038Z</ResponseDateTime>
<Payload>
</Payload>
</FormattedResponseApiData>
| Attribute Name | Description |
|---|---|
| CorrelationId | A string that will be the same as the CorrelationId that initiated this response |
| Payload | The content that was received after a method was invoked. If the payload is XML (as opposed to a single string response) then the XML will be escaped. |
| ResponseDateTime | Time stamp created by the Intermediary service when it receives a response from the API Service |
Event Message Envelope
<?xml version="1.0" encoding="utf-16" standalone="yes"?>
<ApiEvent>
<Name>jobUpdated</Name>
<PayLoad>
</PayLoad>
</ApiEvent>
| Attribute Name | Description |
|---|---|
| Name | The name of the event that was raised |
| Payload | The content of the event |
Valid Payload content messages are defined in the Sequoia API documentation
Dead Letter Message Envelope
Plug-ins that do not have a native dead letter queue such as SQL server or file system plug-ins can implement a manual dead letter queue. This will allow messages that faulted before reaching the API Service to be moved for later manual re-processing and auditing.
<?xml version="1.0" encoding="utf-16" standalone="yes"?>
<DeadLetterMessage>
<OriginalMessage>Escaped original message</OriginalMessage>
<ExceptionDetail></ExceptionDetail>
<DateTimeCreated>2012-03-22 12:20:07Z</DateTimeCreated>
</DeadLetterMessage>
| Attribute Name | Description |
|---|---|
| OriginalMessage | Original message that was place on the IN queue. This is an XML message and will be escaped. |
| ExceptionDetail | Exception detail as provided by the Intermediary Service |
| DateTimeCreated | Date and Time the message was moved to the Dead Letter queue |
Methods
See the Sequoia API documentation for additional and schema information for supported API methods.
Example Usages
CreateJob
Description
Creates a job record within Sequoia that represents the data passed in the XML document.
Extra Request/Response Schema(s)
Payload: The schema (JobHeader.xsd) is defined in the Sequoia API documentation.
Usage
Calls the 'CreateJob' method on the web service – passing as a payload an XML document formatted to the Jobheader specification as defined in the Sequoia API documentation.
Request:
<?xml version="1.0" encoding="utf-16"?>
<ApiRequestMessage>
<Action>CreateJob</Action>
<CorrelationId>0000000001</CorrelationId>
<PayLoad>
<![CDATA[<?xml version="1.0"?>
<jobHeader xmlns="asm.org.uk/Sequoia/JobHeader"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="asm.org.uk/Sequoia/JobHeader JobHeader.xsd"
xmlns:N1="asm.org.uk/Sequoia/Account"
xmlns:N2="asm.org.uk/Sequoia/AccountAddress">
<jobType>AI</jobType>
<customer>
<N1:shortCode>PEN0001</N1:shortCode>
<N1:name>API Test Client</N1:name>
<N1:address>
<N2:street1>PUMPKIN STREET</N2:street1>
<N2:countryCode>GB</N2:countryCode>
<N2:description>SaveJob Test Entry</N2:description>
</N1:address>
</customer>
</jobHeader>]]>
</PayLoad>
</ApiRequestMessage>
Response:
<?xml version="1.0"?>
<FormattedResponseApiData
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<CorrelationId>0000000001</CorrelationId>
<ResponseDateTime>2019-03-18T14:20:09.5658038Z</ResponseDateTime>
<Payload><![CDATA[<SequoiaApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Errors />
<ReturnValue>AI-000000000268 </ReturnValue>
</SequoiaApiResponse>]]></Payload>
</FormattedResponseApiData>
GetAgentInventoriesFromDate
Description
Gets a summary list of CCS-UK import agent inventory records modified since the specified date until the present.
Extra Request/Response Schema(s)
Response: The schema is defined in the Sequoia API documentation.
Usage
Calls the GetAgentInventoriesFromDate method on the API service specifying the start date/time you want to pull back records for.
A list of badge codes should also be supplied to determine which records get returned.
The return format is specified in the Sequoia API documentation.
Request:
<?xml version="1.0" encoding="utf-16"?>
<ApiRequestMessage>
<Action>GetAgentInventoriesFromDate</Action>
<CorrelationId>0000000001</CorrelationId>
<PayLoad>
<![CDATA[<ModifiedRecordsRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ModifiedSince>2019-01-01T09:50:45.1158724+00:00</ModifiedSince>
<BadgeList>
<string>DMX</string>
<string>DNX</string>
</BadgeList>
</ModifiedRecordsRequest>]]>
</PayLoad>
</ApiRequestMessage>
Response:
<?xml version="1.0"?>
<FormattedResponseApiData xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<CorrelationId>0000000001</CorrelationId>
<ResponseDateTime>2019-03-18T15:09:54.1830448Z</ResponseDateTime>
<Payload><![CDATA[<SequoiaRecordListResponse
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Errors />
<ReturnValue><?xml version="1.0"?>
<agentInventories
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="asm.org.uk/Sequoia/AgentInventoryList">
<agentInventory>
<shed xmlns="asm.org.uk/Sequoia/AgentInventoryIdentifier">TDX</shed>
<arrivalPort xmlns="asm.org.uk/Sequoia/AgentInventoryIdentifier">LHR</arrivalPort>
<masterAirwayBillPrefix xmlns="asm.org.uk/Sequoia/AgentInventoryIdentifier">057</masterAirwayBillPrefix>
<masterAirwayBillNumber xmlns="asm.org.uk/Sequoia/AgentInventoryIdentifier">08011901</masterAirwayBillNumber>
<houseAirwayBillNumber xmlns="asm.org.uk/Sequoia/AgentInventoryIdentifier">HAWB0001</houseAirwayBillNumber>
<nominatedAgent xmlns="asm.org.uk/Sequoia/AgentInventoryIdentifier">DMX</nominatedAgent>
</agentInventory>
<agentInventory>
<shed xmlns="asm.org.uk/Sequoia/AgentInventoryIdentifier">TDX</shed>
<arrivalPort xmlns="asm.org.uk/Sequoia/AgentInventoryIdentifier">LHR</arrivalPort>
<masterAirwayBillPrefix xmlns="asm.org.uk/Sequoia/AgentInventoryIdentifier">057</masterAirwayBillPrefix>
<masterAirwayBillNumber xmlns="asm.org.uk/Sequoia/AgentInventoryIdentifier">09111801</masterAirwayBillNumber>
<houseAirwayBillNumber xmlns="asm.org.uk/Sequoia/AgentInventoryIdentifier">HAWB0002</houseAirwayBillNumber>
<nominatedAgent xmlns="asm.org.uk/Sequoia/AgentInventoryIdentifier">DMX</nominatedAgent>
</agentInventory>
</agentInventories>
</ReturnValue>
<RecordsReturned>10</RecordsReturned><QueryToken>bccf4afa-479a-4e3f-b95c-95fd821ce0f2</QueryToken></SequoiaRecordListResponse>]]></Payload>
</FormattedResponseApiData>
GetAgentInventoryRecord
Description
Gets a specific agent inventory record given its natural key.
Extra Request/Response Schema(s)
Request: The schema is defined in the Sequoia API documentation.
Response: The schema is defined in the Sequoia API documentation.
Usage
Calls the GetAgentInventoryRecord method on the web service, passing in the details of the agent inventory record which form its natural key.
If a matching record is located, the detail of the agent inventory record will be returned.
Request:
<?xml version="1.0" encoding="utf-16"?>
<ApiRequestMessage>
<Action>GetAgentInventoryRecord</Action>
<CorrelationId>0000000001</CorrelationId>
<PayLoad>
<![CDATA[<?xml version="1.0" encoding="utf-16"?>
<this:agentInventoryReference
xmlns:this="asm.org.uk/Sequoia/AgentInventoryReference"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsRef="asm.org.uk/Sequoia/AgentInventoryIdentifier">
<this:agentInventoryIdentity>
<xsRef:shed>TDX</xsRef:shed>
<xsRef:arrivalPort>LHR</xsRef:arrivalPort>
<xsRef:masterAirwayBillPrefix>057</xsRef:masterAirwayBillPrefix>
<xsRef:masterAirwayBillNumber>15031901</xsRef:masterAirwayBillNumber>
<xsRef:nominatedAgent>DMX</xsRef:nominatedAgent>
</this:agentInventoryIdentity>
</this:agentInventoryReference>]]>
</PayLoad>
</ApiRequestMessage>
Response:
<?xml version="1.0"?>
<FormattedResponseApiData xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<CorrelationId>0000000001</CorrelationId>
<ResponseDateTime>2019-03-18T15:21:45.8863323Z</ResponseDateTime>
<Payload><![CDATA[<SequoiaApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Errors />
<ReturnValue><?xml version="1.0"?>
<agentInventory xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="asm.org.uk/Sequoia/AgentInventory">
<inventoryType>Basic</inventoryType>
<shed>TDX</shed>
<arrivalPort>
<iataPortCode xmlns="asm.org.uk/Sequoia/UnLocation">LHR</iataPortCode>
</arrivalPort>
<masterAirwayBillPrefix>057</masterAirwayBillPrefix>
<masterAirwayBillNumber>15031901</masterAirwayBillNumber>
<nominatedAgent>DMX</nominatedAgent>
<originPort>
<iataPortCode xmlns="asm.org.uk/Sequoia/UnLocation">LAX</iataPortCode>
</originPort>
<destinationPort>
<iataPortCode xmlns="asm.org.uk/Sequoia/UnLocation">LHR</iataPortCode>
</destinationPort>
<airCarrier>
<carrierCode xmlns="asm.org.uk/Sequoia/AirCarrier">AF</carrierCode>
</airCarrier>
<flightNumber>213</flightNumber>
<flightDate>2019-03-15T00:00:00</flightDate>
<npx>55</npx>
<npr>0</npr>
<grossWeight>150</grossWeight>
<goodsDescription>PARTS</goodsDescription>
<sdc>T</sdc>
<status2Set>true</status2Set>
<ccsCreationTime>2019-03-15T13:41:00</ccsCreationTime>
<createdOn>2019-03-15T13:42:02.013</createdOn>
<modifiedOn>2019-03-15T13:42:32.903</modifiedOn>
</agentInventory>
</ReturnValue>
</SequoiaApiResponse>]]></Payload>
</FormattedResponseApiData>
GetFrontierDeclarationResponse
Description
Gets 'significant' declaration response data for the declaration identified from the passed in DUCR (Declaration UCR)/DUCR part number or Job Reference.
Extra Request/Response Schema(s)
Request: The schema (DeclarationResponseRequest.xsd) is specified in the Sequoia API documentation.
Response: The schema (DeclarationResponse.xsd) is specified in the Sequoia API documentation.
Usage
Calls the 'GetFrontierDeclarationResponse' method on the web service passing in the details of the declaration (DUCR/DUCR part number or Job Reference).
If matching declaration response data is located, the detail will be returned.
Request:
<?xml version="1.0" encoding="utf-16"?>
<ApiRequestMessage>
<Action>GetFrontierDeclarationResponse</Action>
<CorrelationId>0000000001</CorrelationId>
<PayLoad>
<![CDATA[<?xml version="1.0" encoding="utf-16"?><declarationReference xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="asm.org.uk/Sequoia/DeclarationResponseRequest">
<ducr>
<declarationUcr>9GB493594008000-SCA001</declarationUcr>
</ducr>
</declarationReference>]]>
</PayLoad>
</ApiRequestMessage>
Response:
<?xml version="1.0"?>
<FormattedResponseApiData xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<CorrelationId>0000000001</CorrelationId>
<ResponseDateTime>2019-03-18T15:25:36.5292091Z</ResponseDateTime>
<Payload><![CDATA[<SequoiaApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Errors />
<ReturnValue>
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="asm.org.uk/Sequoia/DeclarationResponse">
<entryNumber>000623F</entryNumber>
<epu>120 </epu>
<route>6 </route>
<entryDate>2019-03-13T09:41:00</entryDate>
<totalDuty>27.02</totalDuty>
<totalVat>120.4</totalVat>
<ics>00</ics>
<firstDanPrefix>A</firstDanPrefix>
<firstDefermentNumber>8833614</firstDefermentNumber>
</response>
</ReturnValue>
</SequoiaApiResponse>]]></Payload>
</FormattedResponseApiData>
RecieveNotification
Description
The Sequoia API will raise events that it has subscribed to. These messages are not related to a client initiated request.
Usage
There is no direct usage.
Example Events:
The event payload will be wrapped in a CDATA section within the payload element.
jobUpdated event:
<?xml version="1.0" encoding="utf-16" standalone="yes"?>
<ApiEvent>
<Name>jobUpdated</Name>
<PayLoad><![CDATA[AF1403001]]></PayLoad>
</ApiEvent>
declarationAcceptanceNotification event:
<?xml version="1.0" encoding="utf-16" standalone="yes"?>
<ApiEvent>
<Name>declarationAcceptanceNotification</Name>
<PayLoad><![CDATA[<?xml version="1.0"?>
<declarationAcceptanceNotification
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="asm.org.uk/Sequoia/DeclarationAcceptanceNotification">
<declarationType>IFD</declarationType>
<declarationUcr>9GB493948289000-AF1803001A</declarationUcr>
<traderReference>AF1803001A</traderReference>
<entryVersion>1</entryVersion>
<epu>120</epu>
<entryNumber>000704E</entryNumber>
<route>6</route>
<entryDateTime>2019-03-18T15:38:00</entryDateTime>
<acceptanceDateTime>2019-03-18T15:38:00</acceptanceDateTime>
<totalDuty>19.96</totalDuty>
<totalVat>88.95</totalVat>
<totalOther>0</totalOther>
<ics>00</ics>
<firstDefermentNumber>8833614</firstDefermentNumber>
<consignorEori />
<consigneeEori>GB493594008000</consigneeEori>
<externalReferences />
</declarationAcceptanceNotification>]]></PayLoad>
</ApiEvent>
GetMetaData
Description
Gets the schema XSD for the specified namespace.
Extra Request/Response Schema(s)
Request: The schema is defined in the Sequoia API documentation Response: The schema is defined in the Sequoia API documentation
Usage
Call the 'GetMetaData' method on the web service passing in the schema name.
If a schema is found then it will be returned in the content.
Request:
<?xml version="1.0" encoding="utf-16"?>
<ApiRequestMessage>
<Action>GetMetaData</Action>
<CorrelationId>0000000001</CorrelationId>
<PayLoad>DeclarationAcceptanceNotification.xsd</PayLoad>
</ApiRequestMessage>
Response:
<?xml version="1.0"?>
<FormattedResponseApiData xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<CorrelationId>0000000001</CorrelationId>
<ResponseDateTime>2019-03-18T15:43:39.6648443Z</ResponseDateTime>
<Payload><![CDATA[<xs:schema elementFormDefault="qualified" attributeFormDefault="unqualified"
xmlns="DeclarationAcceptanceNotification"
xmlns:this="asm.org.uk/Sequoia/DeclarationAcceptanceNotification"
targetNamespace="asm.org.uk/Sequoia/DeclarationAcceptanceNotification"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:complexType name="declarationAcceptanceNotification">
<xs:sequence>
<xs:element name="declarationType" minOccurs="1" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="IFD"/>
<xs:enumeration value="SFD"/>
<xs:enumeration value="ISD"/>
<xs:enumeration value="ISW"/>
<xs:enumeration value="IFW"/>
<xs:enumeration value="ICR"/>
<xs:enumeration value="EFD"/>
<xs:enumeration value="ELP"/>
<xs:enumeration value="ESP"/>
<xs:enumeration value="ESD"/>
<xs:enumeration value="ECR"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="declarationUcr" minOccurs="1" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:pattern value="[0-9][A-Z][A-Z][\-A-Z0-9\(\)]{1,32}"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="ucrPartNumber" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:pattern value="[0-9]{1,3}[A-Z]?"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="masterUcr" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:pattern value="[A-Z0-9\-\(\)/: ]{1,35}"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="traderReference" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="21"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="entryVersion" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:pattern value="[0-9]{1,2}"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="epu" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:pattern value="[0-9]{3}"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="entryNumber" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:pattern value="[A-Z0-9]{7}"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="route" minOccurs ="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:pattern value="[A-Z0-9]{1,2}"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="entryDateTime" type="xs:dateTime" minOccurs="0" maxOccurs="1"/>
<xs:element name="acceptanceDateTime" type="xs:dateTime" minOccurs="0" maxOccurs="1"/>
<xs:element name="totalDuty" type="xs:decimal" nillable="true" minOccurs="0" maxOccurs="1"/>
<xs:element name="totalVat" type="xs:decimal" nillable="true" minOccurs="0" maxOccurs="1"/>
<xs:element name="totalOther" type="xs:decimal" nillable="true" minOccurs="0" maxOccurs="1"/>
<xs:element name="soe" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:pattern value="[A-Z0-9]{1}"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name ="ics" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:pattern value="[A-Z0-9]{2}"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="mrn" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:maxLength value="25"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="firstDefermentNumber" type="xs:string" minOccurs="0" maxOccurs="1"/>
<xs:element name="secondDefermentNumber" type="xs:string" minOccurs="0" maxOccurs="1"/>
<xs:element name="consignorEori" type="xs:string" minOccurs="0" maxOccurs="1"/>
<xs:element name="consigneeEori" type="xs:string" minOccurs="0" maxOccurs="1"/>
<xs:element name="jobReference" type="xs:string" minOccurs="0" maxOccurs="1"/>
<xs:element name="externalReferences" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:element name="externalJobReference" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="code" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="5"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="description" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="50"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:schema>
]]></Payload>
</FormattedResponseApiData>
Plug-ins
Overview
The intermediary service can load multiple plug-ins at a time. A plug-in is responsible for providing the Request messages to the service and handling the response and event messages.
Currently available plug-ins
| Name | Description |
|---|---|
| File System | Reads messages from an IN folder and writes responses and events into an OUT folder. |
File System Plug-in
Overview
The file system plug-in is responsible for reading request messages from external applications from an IN folder and sending them to the Sequoia API service and writing response and event messages back into an OUT folder.
Security
Access to the IN and OUT folders should be restricted appropriately as the Intermediary service will process all message found in the IN folder.
Configuration
The plug-in is configured via the application's configuration file:
ASM.Sequoia.Api.IntermediaryService.exe.config
Configure the injection container by adding the following in the <typeAliases> node:
<!-- FileSystem Processor -->
<typeAlias alias="FileSystemMessageProcessor" type="ASM.Sequoia.Api.IntermediaryService.FileSystem.FileSystemMessageProcessor, ASM.Sequoia.Api.IntermediaryService.FileSystem"/>
<!-- FileSystem Processor -->
<register name="FileSystemProcessor" type="IApiMessageProcessor" mapTo="FileSystemMessageProcessor">
<lifetime type="singleton"/>
</register>
Installing the plug-in
Create a sub-directory within the API Intermediary service installation directory (by default this will be C:\Program Files (x86)\ASM\Sequoia Server\ApiIntermediary).
Extract the contents of the FileSystem plug-in zip file to this sub-directory.
Open a command prompt with Administrative privileges. Run InstallUtil.exe with the /i install switch against the ASM.Sequoia.Api.IntermediaryService.FileSystem.Configuration.dll file.
Configuring the plug-in
Connection properties are set by setting the values via the server side Sequoia configuration application:
| Property | Description |
|---|---|
| Requests IN Folder | The folder Sequoia will scan to pick up request messages from the external application. |
| Responses OUT Folder | The folder Sequoia will use to write response and notification messages to. |
| DeadLetter Folder | The folder where messages will be moved by Sequoia when they cannot be processed due to an exception. |
To configure the plug-in to output event data received by the API service, click the ellipsis button on the "Processed Events" control and add the required event name(s):
The list of available events can be found in the API Service configuration file (ASM.Sequoia.Api.exe.config).
Troubleshooting Guide
Things to check if a connection cannot be made to the API service:
- Has an HTTP reservation been made? This needs to be made for any http connection when using a version of the Windows operating system that features UAC.
Connections required by default are for the connection and the call-back channel. - An HTTP connection can be stopped by the local firewall. An exception should be added to the firewall to allow communications to the API.
- An HTTP connection can end up routed through a proxy depending on your network setup. An exception should be made for communications with the API as it is likely that a call-back channel will fail to initialise.
- Has a user been added to Sequoia via the 'Sequoia configuration' application with appropriate permissions?
Callback port conflict
If the following error should occur when attempting to start the API Intermediary service:
HTTP could not register URL http://+:80/Temporary_Listen_Addresses/b16b1f48-ff14-4751-88c1-5d4e92f71cd3/ because TCP port 80 is being used by another application
You will need to add default client base address configuration to WcfServiceClients.config in multiple locations.
Update the files in the following locations:
- ..\Sequoia Server\ApiIntermediary\WcfBindings.config
- ..\Sequoia Server\Common\Configuration\WcfBindings.config
The new attribute should be added to the wsDualHttpBinding with the binding name: WSDualHttpBinding_ISequoiaApiService, and should be configured as follows:
clientBaseAddress="http://localhost:{PORT}/Asm/Sequoia"
where port should be an available port on the machine. If unsure of which port to use, check with internal IT.
A completed example should look like this:
<wsDualHttpBinding>
<binding name="WSDualHttpBinding_ISequoiaApiService" clientBaseAddress="http://localhost:{PORT}/Asm/Sequoia" closeTimeout="00:01:00" openTimeout="00:01:00" receiveTimeout="00:10:00" sendTimeout="00:01:00" bypassProxyOnLocal="false" transactionFlow="false" hostNameComparisonMode="StrongWildcard" maxBufferPoolSize="524288" maxReceivedMessageSize="4194304" messageEncoding="Text" textEncoding="utf-8" useDefaultWebProxy="true">
<readerQuotas maxDepth="32" maxStringContentLength="2147483647" maxArrayLength="16384" maxBytesPerRead="4096" maxNameTableCharCount="16384"/>
<reliableSession ordered="true" inactivityTimeout="20:00:00"/>
<security mode="None">
<message clientCredentialType="Windows" negotiateServiceCredential="true"/>
</security>
</binding>
HTTP namespace reservation
If UAC is enabled on the operating system, you may need to add a http namespace reservation for the port used in the newly configured clientBaseAddress.
netsh http add urlacl url=http://+:<PORT>/Asm/Sequoia user=<USERNAME>