How to setup and test the Syracuse integrated web services on Version 12

9 minute read time.

Evening readers,

Today’s blog will be about how to setup and test the web services in V12. There are several ways to test (like SOAPUI and POSTMAN) but one way to setup. We will cover the most basic way to setup and test to get it up and running for something like a test environment or just for messing around.

Before you start you will need access to the Administration module. So, that means you will need a login with that access, preferably the ADMIN account. Technically any will do as long as the functions for web services are available (that were about to discuss). You will also need access to the Development Module as we will need to take a quick visit there for the Web services publication (discussed later).

First step is to make sure you have Syracuse nodes for web services to run off of. This requires you to go to the HOST function under administration, administration, servers.

You may have one or several records in the HOST function. These records are the configuration for each Syracuse server that is configured for your environment. Here, I only have one record because I only have one configured Syracuse Server.

Now, if you have more than one, someone will have to make a business decision on whether or not to have a web service node on each server, one, server with all the nodes, or some sort of combination of. As you can see, for me, I only have one option.

We’re going to focus in on the field value “Number of web service child processes”. For Web service to work, you have to have at least one (1) value in there. Technically you can put any numerical value in there as long as the server has the proper resources to handle it.

I already have a 1 in mine but if you have a zero (0) then you will want to edit the value and put at least 1 if not more. Once set you can close out back to the main navigation page.

Next, we are going to go to the Classic SOAP pools configuration function. You can also find this under administration, administration, Web services.

  

If you have not set anything up, you should not have any records (like mine). Click the “New SOAP pool” button to get started.

At this screen, you will fill out the appropriate information pertaining to the folder (endpoint) you are using and what user you want to use to manage the channels.

I have color coded the fields so that I can more easily discuss what to do with each field.

Starting from the top, the Alias field (purple) is the name of the pool that you want to label it as. Remember what you call it as we will need it during testing.

The Auto Start checkbox (pink). This is if you want the pool to automatically start when the Syracuse service is started or restarted. Most people check it.

The Endpoint field (yellow). This is the folder endpoint in which the pool will be attached to. Note that the pools are specific to a single folder and multiple folders cannot share a single pool.

The X3 runtime tags field (red). This field is not mandatory, but you can use the X3 tags to force the pool to utilize a specific runtime process server. It exists to give users more flexibility with how data is running.

The Locale field (blue). This is the language code for the system. It should match with the primary language for the environment.

The User field (orange). The user field is for the Primary user code that the pool will use to manage the incoming data and how the channels connect to the system to submit the data. I have created a follow up blog on how to create a user specifically for web service pools and channels. It will be posted at the end of this blog Blush

The Maximum size and Initialization size fields (green). The max size is used to tell the pool the max number of channels it can have. The init size is the starting number of fields. The way it works is that the pool starts, creates the init size of channels then as it needs more it will generate more channels until it hits the max size and stops. If the load on the channel stops for the unused lifetime value, then it will drop those channels until its back to the original init size.

Lastly is the unused lifetime and lifetime fields (grey). The unused is how long a channel can sit unused before being dropped or recreated when needed. The Lifetime field is the how long a channel can exist before its recreated. You can read more about these field values by selecting the help button from the right list.

Once you have all the proper values filled in and saved, we can now click the start/update button to start the pool. Note that I am using the ADMIN user in my screenshot as the user code. In a production environment you would not use the ADMIN but create a separate user just for web service calls. The reason is that if you use a user code like ADMIN, every time the pool is started the badge tied to the user is consumed. ADMIN has a ERPDEV badge, and they are rare and expensive. Default environments for X3 only come with 1 or 2 (cannot remember which) but it’s a very low amount. Anyways, the point is, you do not want to be wasting DEV Badges on web calls.

If everything started according to plan, your start/update click should have started the pool with a popup (for progress) and eventually the pool starting with the shown channels. I highlighted a couple areas in my screenshot.

The Orange outline is the progress of the pool starting the channels.

The Red outline is the pool starting status and if there is any current load.

The Blue outline is the channels starting status.

You can now close and head back to the main navigation screen.

 

Our next stop is the Web Services Publication function. You can find it under Development, Script Dictionary, Scripts. It’s labeled as Web services.

It should look like mine, with a bunch of stuff on the left list.

There will be a ton of stuff here, but you can ignore most of it. All we are looking for is a publication called ECMSOH. This is an E-commerce publication for sales order. We are using this one because it is standard, already setup, and it’s configured for Sales Order. The only way this one will not work for you is if you do not use sales order module. If you do not have Sales module, you can use ECMBPC instead. It’s for the Customer function to pull up customer listings.

Once you locate the ECMSOH/ECMBPC you will want to click the save button on the right list. If you do not have the save option available, then someone’s already come in and saved it (which is fine).

Next, click the publication button from the top window bar. Note that when you click the publication button you should see the “Published on” field update to the current date/time.

If it changes correctly, we are done. Essentially, we are just coming into the publications and revalidating a publication so that we can use it with the web services to test with. Take note of the publication name because we will need it.

Ok, back to the navigation pages again. We can now give it a test and see how it works. We are going to navigate to the Classic SOAP web services function which you can find under Administration, Administration, Web services.

 

The Classic SOAP web services function should open up to a single record. Here, you will click on the CAdxWebServiceXmlCC name (should act like a url link).

It should expand into a test and stub area like my screenshot below. If you click the > thingy it will show you the testing options available.

 

If we take a closer look at the test options, you can see the available testing that you can do. We are going to use something that is non-damaging which will be similar to a select. You will want to find the QUERY option. This will allow us to request a top selection; like a top 5 or first 5 results.

Click on the query option and it should load you into this request page.

From here you will fill in the following information as it pertains to your created environment. For my specific server I am using the following information:

Language code: ENG

Pool alias: WSP

Pool ID and Request configuration you can skip

Public name: ECMSOH

A quick breakdown of the fields.

The Language code is the same code that you would use for the pools/channels. ENG is short for English, FRA is short for French, etc.. if you are using another language code and do not know the abbreviated code you can check the online help.

The pool alias is the name of the pool you created earlier. I called mine WSP for web service pool.

The pool Id we do not use unless you want it to go to a specific pool ID

The request configuration is used if you would to add code for formatting purposes or changing the code output to be specific to xml or json

The public name is the publication name that you want to use in the testing. In my example we are using ECMSOH

The object keys are used for adding specific filters like by order name, or something like that.

The list size (since we are using query) is for how big of a listing do you want, in terms of records returned. I am using 5 because I just want to see 5 records.

Once its all filled out, hit the invoke button from the top right. This sends the call request to the web services pool to get the information requested. If it works, you should get a returned response with 5 of your sales orders.

 

If you are getting any sort of error or warning message, make sure the pool is running, the publication name is correct, the publication has been revalidated, and the request information is correct.

Note that the information you type in the request needs to be exactly is it is displayed. As in, if stuff is capitalized you should type it in with capitals, etc… 

If you are getting results similar to mine, then everything is working. You have officially tested out Web services and made sure it set up and working correctly. Congratulations.

Thanks for taking the time to read this,

Next up for blogs is how to setup a user specially for web services. Check it out HERE!

  • Hi  , I have the same issues, and I can check that the returned fields are fields of Selection Screen of BPC Object. 

    ...

    And if you try to modify Selection screen ( add/modify/delete field) , SoapUI query returns error :

    @X3.TRT/AWEB$adx 697 : Variable inexistente WW_SEL7.
    I don't understand relation about Selection screen of BPC and webservice.
      can you confirm?

  • HI Chris,

    We are using apps.developer-sage.com/ and have created a WorkSpace, created an App with the API credentials and set the API keys to postman and still cant get more than the 5 fields from the Web Service we created as a duplicate of WS_BPC from the seed folder.

    Would SOUPUI not work the same as Postman?

    The 5 fields being returned are not even matching the top 5 columns which one would think it would follow.

    <RESULT DIM="10000" SIZE="1">
    <LIN NUM="1">
    <FLD NAME="BPCNUM" TYPE="Char">APB-100000</FLD>
    <FLD NAME="BPCNAM" TYPE="Char">ASIA PACIFIC BRANDS PTY LTD</FLD>
    <FLD NAME="C3" TYPE="Char"/>
    <FLD NAME="BPCSHO" TYPE="Char"/>
    <FLD MENULAB="Normal" MENULOCAL="401" NAME="BPCTYP" TYPE="Integer">1</FLD>
    <FLD NAME="POSCOD" TYPE="Char">2140</FLD>
    <FLD NAME="PTE" TYPE="Char">CHQ30EOM</FLD>
    </LIN>
    </RESULT>

  • On a brand new endpoint you will not have any web publications. the ones you show above came from when you installed X3-Services for Mobile Automation. If you want to review the longer listing that was created for the demonstration, you can find these in the SEED demo Endpoint. You would have to import that into your environment to get the listings I used.

  • Hi  , when you build the web server publication you can define the columns on the Mapping section.

    This is the columns or fields that will be returned when using SOAPUI. note that when you use the Query with a set top number of records, it reduces it to only the required fields so that the listing is not overly long.

  • Hi Chris,

    How do we edit the Web Service to select specific columns so that we control what fields are being accessed?

    The Query method only shows 5 lines from the BPC object when testing the connection. So how do we get the full list of all fields?

    Can you breakdown the list of SOAP actions and what results should be expected?

    Thanks in advance.