Developing with Web Services
Less than to read
In the cloud, you can import or export using data files but you need to manually drag and drop the files. You can automate the process with our web services, which allow you to exchange data directly between your application and X3.
In addition to running in real time, web services can also be executed by our batch server. This can be useful when you need to process data at specific times during the day, or on a recurring basis.
Available Web Services
Standard SOAP web services are supplied to manage these operations. They use the standard SOAP web service connection pools and can be called from any program that can:
- Connect to the SOAP web service server integrated in the X3 platform
- Authenticate with the available authentication methods
- Send a normalized SOAP message as indicated in the SOAP web service guide and receive the answer
The SOAP web services used are subprograms associated with web services. Their names are the following:
| Service name | Subprogram | Description |
|---|---|---|
| AOWSIMPORT | AOWSIMPORT.IMPORT | Imports data based on an import template |
| AOWSEXPORT | AOWSEXPORT.EXPORT | Exports data associated with a template and parameters |
| AOWSBATGET | AOWSGETBATCH.GET | Retrieves information about a batch import/export request |
These SOAP web services can be called from any program that can perform a SOAP web service in the correct format as described below. You can, for example, write in Java, PHP, JavaScript, .NET, C, etc.
Perform an Import
The import web service contains the following arguments:
| Group | Code | Description | Parameter type | Argument type |
|---|---|---|---|---|
| GRP1 | I_MODIMP | Template | Char | Sent |
| GRP1 | I_AOWSTA | Import/export temporary storage | Char | Sent |
| GRP1 | I_EXEC | Execution type | Char | Sent |
| GRP1 | I_RECORDSEP | Record separator | Char | Sent |
| GRP1 | I_FILE | File | Clbfile | Sent |
| GRP1 | O_REQNUM | Query | Integer | Returned |
| GRP1 | O_STATUS | Status | Integer | Returned |
| GRP1 | O_MESSA | Message | Char | Returned |
The parameters sent are:
- The template code (BPC for example)
- An import/export temporary storage flag (YES or NO) to send the erroneous lines in the temporary import/export storage space
- An execution flag (REALTIME or BATCH)
- A character used as a record separator in the returned data feed
- A clob containing the file to be imported. This file must end with the characters END.
For example, if you import two lines with a string, a date, and a numeric value, and if the record separator is “|”, the correct clob contents would be: STRING1;20170203;1| STRING2;20160512;33|END**
The SOAP parameters returned are:
- The status (1=OK, 0=errors).
- The log file produced by the export as an array of a structure containing a status (1=warning, 3=error) and the corresponding text message.
The values returned are:
- An integer containing the request ID if a batch execution was requested. This value is used later as a parameter to indicate the status of the batch request.
- The web service status (0=OK, otherwise it is an error)
- A message if an error occurred
Import Examples
- The Get started guide has step-by-step examples of importing and exporting.
- Example of importing a customer in real time
- Example of importing in real time with a parameter error
- Example of importing in real time with data errors
Perform an Export
The export web service contains the following arguments:
| Group | Code | Description | Parameter type | Dim | Argument type |
|---|---|---|---|---|---|
| GRP1 | I_MODEXP | Template | Char | 1 | Sent |
| GRP1 | I_CHRONO | Sequence no. | Char | 1 | Sent |
| GRP2 | I_TCRITERE | Criteria | Char | 10 | Sent |
| GRP3 | I_EXEC | Execution type | Char | 1 | Sent |
| GRP3 | I_RECORDSEP | Record separator | Char | 1 | Sent |
| GRP3 | O_FILE | Data file | Clbfile | 1 | Returned |
| GRP3 | O_REQNUM | Query | Integer | 1 | Returned |
| GRP3 | O_STATUS | Status | Integer | 1 | Returned |
| GRP3 | O_MESSA | Message | Char | 1 | Returned |
The parameters sent are:
- The template code (BPC for example)
- A chrono flag (YES or NO) to trigger an export with chrono management and prevent the export of duplicate records
- An array of criteria (filters expressed in X3 language such as: [F:BPC]BPCSTA=1)
- An execution flag (REALTIME or BATCH)
- A character used as a record separator in the returned data feed
The SOAP parameters returned are:
- The status (1=OK, 0=errors)
- The log file produced by the export as an array of a structure containing a status (1=warning, 3=error) and the corresponding text message
The values returned are:
- A clob containing the file produced by the export if the execution is in real time
- An integer containing the request ID if a batch execution was requested. This value is used later as a parameter to indicate the status of the batch request.
- The web service status (0=OK, otherwise it is an error)
- A message if an error occurred
Export examples
- The Get started guide has step-by-step examples of importing and exporting.
- Example of exporting a customer in real time
- Example of exporting in real time with a parameter error
Get Information About a Batch Task
After performing an import or export with the BATCH option, the status of the batch server job can be querried with this web service.
More information about batch processing of imports and exports can be found in Batch Processing for Import/Export Templates, as well as our Online help center.
This web service contains the following arguments:
| Group | Code | Description | Parameter type | Argument type |
|---|---|---|---|---|
| GRP1 | I_TACHE | Batch task | Char | Sent |
| GRP1 | I_REQNUM | Query | Integer | Sent |
| GRP1 | I_GETTRA | Log | Char | Sent |
| GRP1 | O_STAREQ | Status | Integer | Returned |
| GRP1 | O_MESREQ | Message | Char | Returned |
| GRP1 | O_FILE | File | Clbfile | Returned |
| GRP1 | O_FILETRA | File | Clbfile | Returned |
| GRP1 | O_STATUS | Status | Integer | Returned |
| GRP1 | O_MESSA | Message | Char | Returned |
The parameters sent are:
- The type of batch task (IMPORT or EXPORT)
- The request ID returned by the batch import or export web service (12345 for example)
- A flag (YES or NO) to get the log file returned
The SOAP parameters returned are:
- The status (1=OK, 0=errors)
- The log file produced by the export as an array of a structure containing a status (1=warning, 3=error) and the corresponding text message
The values returned are:
- A numeric value containing the status of the task with the following values:
- 1 = Standby
- 2 = In progress
- 3 = Finished
- 4 = On Hold
- 5 = Killed
- 6 = Canceled
- 7 = Error
- 8 = Overdue
- 9 = Warning
- A text containing the corresponding message (standby, in progress, etc.)
- A clob containing the file returned if the type is EXPORT and if the task is finished with or without errors or warnings
- A clob containing the trace file if it was requested
- The web service status (0=OK, otherwise it is an error)
- A message if an error occurred