Versions Compared

Old Version 4

changes.mady.by.user Schuyler Horky (Unlicensed)

Saved on

compared with

New Version Current

changes.mady.by.user Dan Weber

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Code Block
languagexml
POST /services/ActionCommand.svc/APIExecute HTTP/1.1
Host: NorthScope.example.com
NSLogin: TestAPIUser@NorthScope.example.com
NSAPISession: 00000000-0000-0000-0000-000000000000

<NSRequest>
	<RequestName>ListCompanies</RequestName>
</NSRequest>

Testing the Web Service API via Postman

Testing web service request code can be tricky.

It’s recommended you use a tool like Postman to get started sending web service requests.

In this document, header Postman is a free tool for developers and can be used to test web service requests. You can find it at: https://www.getpostman.com/.

With this tool, it’s easy to test web service requests. Follow these instructions to test your first command.

How to test your first command

Please refer to the screenshot of Postman below. There’s nothing special about Postman, except that it’s a handy tool. But please ensure all the information listed below is

Part 1. Obtain a token

Referencing the two screenshots below, set the following information

Note: This is only necessary if you are using a user that is not setup to use a static token.

Referencing the two screenshots below, set the following information

0. Download and install Postman.

1. Set the URL of the web service request. This is usually the NorthScope URL + '/services/ActionCommand.svc/APIExecute'.

2. Set the request type to POST

...

6. Click the send button to issue the request. The pane in the bottom right should show <Success>true</Success> and have a valid session token you can use for step 2.

Part 2. Send a request for data

1. Modify the bottom left pane to use the ListCompanies request XML.

...

Parameter Name

Required

Comment

OrderItemSK

Yes

The identifier for the Sales Order Line Item being allocated.

LotSK

Yes

The identifier for the Inventory Lot from which the inventory will be drawn.

AllocateUnits

No

The number of Units (in the supplied Unit of Measure) to allocate. Not required if the item is managed by Weight only.

UnitsUOM

No

The Unit of Measure ID for the units in which the inventory is being allocated.

AllocateWeight

No

The amount of Weight (in the supplied Unit of Measure) to allocate. Not required if the item is managed by Units only.

WeightUOM

No

The Unit of Measure ID for the weight in which the inventory is being allocated.

...

Example Requests

Code Block
languagejson
POST /services/ActionCommand.svc/APIExecute HTTP/1.1
Host: NorthScope.example.com
NSLogin: TestAPIUser@NorthScope.example.com
NSAPISession: 00000000-0000-0000-0000-000000000000

{
  "NSRequest": {
    "RequestName": "AllocateSalesOrders",
    "RequestContent": {
      "Allocation": [
        {
          "OrderItemSK": "100",
          "LotSK": "1",
          "AllocateUnits": "5",
          "UnitsUOM": "Case",
          "AllocateWeight": "113.4",
          "WeightUOM": "kg"
        },
        {
          "OrderItemSK": "101",
          "LotSK": "1",
          "AllocateUnits": "5",
          "UnitsUOM": "Case",
          "AllocateWeight": "113.4",
          "WeightUOM": "kg"
        }
      ]
    }
  }
}

...

 Code Block
languagexml
POST /services/ActionCommand.svc/APIExecute HTTP/1.1
Host: NorthScope.example.com
NSLogin: TestAPIUser@NorthScope.example.com
NSAPISession: 00000000-0000-0000-0000-000000000000

<NSRequest>
  <RequestName>AllocateSalesOrders</RequestName>
  <RequestContent>
    <Allocation>
      <OrderItemSK>100</OrderItemSK>
      <LotSK>1</LotSK>
      <AllocateUnits>5</AllocateUnits>
      <UnitsUOM>Case</UnitsUOM>
      <AllocateWeight>113.4</AllocateWeight>
      <WeightUOM>kg</WeightUOM>
    </Allocation>
    <Allocation>
      <OrderItemSK>101</OrderItemSK>
      <LotSK>1</LotSK>
      <AllocateUnits>5</AllocateUnits>
      <UnitsUOM>Case</UnitsUOM>
      <AllocateWeight>113.4</AllocateWeight>
      <WeightUOM>kg</WeightUOM>
    </Allocation>
  </RequestContent>
</NSRequest>
Example Response
This request has no specific response, instead you would receive a generic success or failure with a timestamp and error (assuming the request failed).
...
This request provides a way to leverage NorthScope’s existing mechanism for 3rd party integrations. Using the InsertInboundIntegration web request, data can be inserted into a NorthScope instance’s inbound queue. 
Everything in the <Integ> <Data> </Integ> Data> section is what will be placed into the inbound queue. For more information on the inbound queue and what to send there, see IM Adjustment (XML) for details as an example. The example code below sends a fake transaction ‘TransactionABC’ of type ‘IMTransferXYZ’. To send a different kind of transaction to the inbound queue, simply replace the XML inside the <Integ> <Data> </Integ> Data> section. For building XML to place inside the <Integ> </Integ> section, see IM Adjustment (XML).
...
Example Request
 Code Block
languagexml
POST /services/ActionCommand.svc/APIExecute HTTP/1.1
Host: NorthScope.example.com
NSLogin: TestAPIUser@NorthScope.example.com
NSAPISession: 00000000-0000-0000-0000-000000000000

<NSRequest>
    <RequestName>InsertInboundIntegration</RequestName>
    <RequestContent>
        <InboundIntegration>
            <Created>2019-12-2</Created>
            <SourceSystem>NS Test</SourceSystem>
            <SourceTransactionID>TransactionABC</SourceTransactionID>
            <TransactionType>IMTransferXYZ</TransactionType>
            <Data>
                <TransactionHeader>
                    <TransactionType>Adjustment</TransactionType>
                    <TransactionClassID>Default</TransactionClassID>
                    <TransactionID>A123456</TransactionID>
                    <TransactionStatusName>Ready To Post</TransactionStatusName>
                    <SiteID>ABC</SiteID>
                    <TransactionDate>2017-12-19</TransactionDate>
                    <ReasonCode />
                    <UserID>Integrated</UserID>
                    <CompanyID>XYZ</CompanyID>
                    <TransactionDetail>
                        <ItemSort />
                        <ItemID>1234321</ItemID>
                        <TransactionUnits>5.00000</TransactionUnits>
                        <UnitsUOMID>CASE</UnitsUOMID>
                        <TransactionWeight>150.5500</TransactionWeight>
                        <WeightUOMID>LB</WeightUOMID>
                        <Lot>18001</Lot>
                        <Owner>NLP</Owner>
                    </TransactionDetail>
                </TransactionHeader>
            </Data>
        </InboundIntegration>
    </RequestContent>
</NSRequest>
...
The WhereClause parameter enables only a selection of data to be sent back in the reply, based on filter criteria written with SQL syntax. Any of the UOM schedule properties can be referenced.
Example Request
 Code Block
<NSRequest>
  <RequestName>NorthPacificUOMScheduleMaster</RequestName>
  <RequestContent>
  POST /services/ActionCommand.svc/APIExecute HTTP/1.1
Host: NorthScope.example.com
NSLogin: TestAPIUser@NorthScope.example.com
NSAPISession: 00000000-0000-0000-0000-000000000000

<NSRequest>
  <RequestName>NorthPacificUOMScheduleMaster</RequestName>
  <RequestContent>
    <DataEntityCompanySK>1</DataEntityCompanySK>
  </RequestContent>
</NSRequest>
...
The WhereClause parameter enables only a selection of data to be sent back in the reply, based on filter criteria written with SQL syntax. Any of the site properties can be referenced.
Example Request
 Code Block
languagexml
POST /services/ActionCommand.svc/APIExecute HTTP/1.1
Host: NorthScope.example.com
NSLogin: TestAPIUser@NorthScope.example.com
NSAPISession: 00000000-0000-0000-0000-000000000000

<NSRequest>
	<RequestName>ListSites</RequestName>
	<RequestContent>
		<DataEntityCompanySK>1</DataEntityCompanySK>
		<WhereClause>State = 'WA' OR SiteName LIKE '%a%'</WhereClause>
	</RequestContent>
</NSRequest>
...
The WhereClause parameter enables only a selection of data to be sent back in the reply, based on filter criteria written with SQL syntax. Any of the sales order (not detail) properties can be referenced.
Example Request
 Code Block
<NSRequest>
  <RequestName>NorthPacificSalesOrder</RequestName>
  <RequestContent>
    <DataEntityCompanySK>1</DataEntityCompanySK>
    POST /services/ActionCommand.svc/APIExecute HTTP/1.1
Host: NorthScope.example.com
NSLogin: TestAPIUser@NorthScope.example.com
NSAPISession: 00000000-0000-0000-0000-000000000000

<NSRequest>
  <RequestName>NorthPacificSalesOrder</RequestName>
  <RequestContent>
    <DataEntityCompanySK>1</DataEntityCompanySK>
    <WhereClause>SiteID = '400'</WhereClause>
  </RequestContent>
</NSRequest>
...
The WhereClause parameter enables only a selection of data to be sent back in the reply, based on filter criteria written with SQL syntax. Any of the Item properties can be referenced.
Example Request
 Code Block
POST /services/ActionCommand.svc/APIExecute HTTP/1.1
Host: NorthScope.example.com
NSLogin: TestAPIUser@NorthScope.example.com
NSAPISession: 00000000-0000-0000-0000-000000000000

<NSRequest>
  <RequestName>NorthPacificItemMaster</RequestName>
  <RequestContent>
    <DataEntityCompanySK>1</DataEntityCompanySK>
  </RequestContent>
</NSRequest>  
...
The WhereClause parameter enables only a selection of data to be sent back in the reply, based on filter criteria written with SQL syntax. Any of the customer address properties can be referenced.
Example Request
 Code Block
languagexml
<NSRequest>
  <RequestName>NorthPacificCustomer</RequestName>
  <RequestContent>
    <DataEntityCompanySK>1</DataEntityCompanySK>
  POST /services/ActionCommand.svc/APIExecute HTTP/1.1
Host: NorthScope.example.com
NSLogin: TestAPIUser@NorthScope.example.com
NSAPISession: 00000000-0000-0000-0000-000000000000

<NSRequest>
  <RequestName>NorthPacificCustomer</RequestName>
  <RequestContent>
    <DataEntityCompanySK>1</DataEntityCompanySK>
  </RequestContent>
</NSRequest>
...
 Code Block
languagexml
<NSResponse>
    <Timestamp>2019-12-02T14:15:07.058</Timestamp>
    <Success>true</Success>
    <CustomerShipToList>
        <CustomerShipTo>
            <CustomerSK>8001</CustomerSK>
            <CustomerID>CustomerID1</CustomerID>
            <CustomerName>Acme Company</CustomerName>
            <AddressID>ACMEADDR1</AddressID>
            <AddressName>Acme Building A</AddressName>
            <AddressLine1>1234 SE StreetName BLD A</AddressLine1>
            <AddressLine2 />
            <City>Seattle</City>
            <State>WA</State>
            <Zip>98125</Zip>
            <Country>USA</Country>
            <AddressTypeEN>3</AddressTypeEN>
            <CompanyID>CompanyID</CompanyID>
        </CustomerShipTo>
        <CustomerShipTo>
            <CustomerSK>8001</CustomerSK>
            <CustomerID>CustomerID1</CustomerID>
            <CustomerName>Acme Company</CustomerName>
            <AddressID>ACMEADDR2</AddressID>
            <AddressName>Acme Building B</AddressName>
            <AddressLine1>1234 SE StreetName BLD A</AddressLine1>
            <AddressLine2 />
            <City>Seattle</City>
            <State>WA</State>
            <Zip>98125</Zip>
            <Country>USA</Country>
            <AddressTypeEN>4</AddressTypeEN>
            <CompanyID>CompanyID</CompanyID>
        </CustomerShipTo>
    </CustomerShipToList>
</NSResponse>
Powershell Client Example
This document would not be complete without at least one example of how a client might access the web service. Below is an example client program that can obtain a token and request a list of companies from a NorthScope web service. Powershell may not be the best tool for your situation, but the client steps will remain the same, as implemented below.
To run this example, be sure to use the correct username and password, and the URL for your NorthScope server. Save as a ps1 file and run via the Windows Powershell application.
 Code Block
languagepowershell
$user="sh@thenlp.com"
$password="admin"
$url="http://doug/test/services/ActionCommand.svc/APIExecute"

#Constructs XML for a login request of the NS <CustomerShipToList>web service handler
$loginReq = "<NSRequest>
   <CustomerShipTo>             <CustomerSK>8001<<RequestName>GenerateSessionToken</CustomerSK>RequestName>
            <CustomerID>CustomerID1</CustomerID>    <RequestContent>
        <CustomerName>Acme Company</CustomerName>             <AddressID>ACMEADDR1</AddressID><LoginEmail>"+$user+"</LoginEmail>
            <AddressName>Acme Building A</AddressName>      <Password>"+$password+"</Password>
      <AddressLine1>1234 SE StreetName BLD A</AddressLine1>      </RequestContent>
      <AddressLine2 />     </NSRequest>"

$webReq = "<NSRequest>
   <City>Seattle</City>             <State>WA<<RequestName>ListCompanies</State>RequestName>
            <Zip>98125</Zip>     <RequestContent>
       <Country>USA</Country>             <AddressTypeEN>3</AddressTypeEN></RequestContent>
            <CompanyID>CompanyID<</CompanyID>NSRequest>"

#region Login and obtain token
$Body  </CustomerShipTo>
        <CustomerShipTo>
            <CustomerSK>8001</CustomerSK>
            <CustomerID>CustomerID1</CustomerID>
            <CustomerName>Acme Company</CustomerName>
            <AddressID>ACMEADDR2</AddressID>
            <AddressName>Acme Building B</AddressName>
            <AddressLine1>1234 SE StreetName BLD A</AddressLine1>
            <AddressLine2 />
            <City>Seattle</City>
            <State>WA</State>
            <Zip>98125</Zip>
            <Country>USA</Country>
            <AddressTypeEN>4</AddressTypeEN>
            <CompanyID>CompanyID</CompanyID>
        </CustomerShipTo>
    </CustomerShipToList>
</NSResponse>= [byte[]][char[]]$loginReq #convert login request to byte array

#build web request login packet
$Request = [System.Net.WebRequest]::Create($url);
$Request.Method = 'POST';
$Request.Accept = "text/html"
$Request.AllowAutoRedirect = $false
$Request.ContentType = "applications/text"
$Request.ContentLength = $Body.length
$Request.TimeOut = 5000000
$Request.KeepAlive = $true
$Request.Headers.Add("Keep-Alive: 300");
$reqst = $Request.getRequestStream()
$reqst.write($Body, 0, $Body.length)
$reqst.flush()
$reqst.close()

#send request and wait for response
[net.httpWebResponse] $res = $Request.getResponse()
$resst = $res.getResponseStream()
$sr = new-object IO.StreamReader($resst)
$result = $sr.ReadToEnd()
$res.close()
$tokenReply = [xml]$result #parse response to xml
#endregion

#region Send web service request
#build the main web request content packet
$Body = [byte[]][char[]]$webReq #convert web request to byte array
$Request = [System.Net.WebRequest]::Create($url);
$Request.Method = 'POST';
$Request.Accept = "text/html"
$Request.AllowAutoRedirect = $false
$Request.ContentType = "applications/text"
$Request.ContentLength = $Body.length
$Request.TimeOut = 5000000
$Request.KeepAlive = $true

#Insert the login and token into the header
$h1 = "NSLogin:"+$user
$h2 = "NSAPISession:"+$tokenReply.NSResponse.ResponseContent.SessionToken
$Request.Headers.Add($h1)
$Request.Headers.Add($h2)

$reqst = $Request.getRequestStream()
$reqst.write($Body, 0, $Body.length)
$reqst.flush()
$reqst.close()

#send request and wait for response
[net.httpWebResponse] $res = $Request.getResponse()
$resst = $res.getResponseStream()
$sr = new-object IO.StreamReader($resst)
$result = $sr.ReadToEnd()
$res.close()
$rep = [xml]$result #parse response to xml
#endregion

$Error = $rep.NSResponse.Error
$ResponseXML = $rep.NSResponse.OuterXml

$Companies = $rep.NSResponse.Companies.Company
$Companies #print retrieved company list