SData web service for Creation @ L.V. Expertise X3

SData web service for Creation

This article describes how to create a new resource with the Web API.

Getting a template resource

To create a new resource, you need to provide valid values for all the mandatory properties of a resource. To ease this the Web API provides a URL that returns a template URL the defaults that have been configured via the class and representation dictionaries. You can retrieve this template resource with an HTTP GET request on the following URL:

http://myserver:myport/api1/x3/erp/MYENDPOINT/MYCLASS/$template?representation=MYREPR.$create

where:

myserver:myport is your server name and port number. For example localhost:8124 if the SAFE X3 web server is installed locally.
MYENDPOINT is the name of your Sage X3 endpoint.
MYCLASS is the name of the class that you want to query. It may be a standard class like BPCUSTOMER or a custom class that you have implemented (see the class dictionaries documentation).
MYREPR is the name of the representation that you want to query. It may be a standard representation like BPCUSTOMER or a custom one (see the representation dictionaries documentation).

Note MYREPR must be a representation for MYCLASS. Otherwise you will get an error. A future version of the Web API will allow you to pass only MYREPR but this version (api1) requires both parameters.

The following URL will return a prototype that gives all the properties present in the representation:

http://myserver:myport/api1/x3/erp/MYENDPOINT/MYCLASS/$prototypes('MYREPR.$create')

The feed returned contains also a lot of meta-data (properties having a name starting with $). The real interesting information start at "$properties" section like the example below:

{..."$properties": {"ORDNUM": {"$title": "{@14573}","$shortTitle": "{@11452}","$type": "application/x-string","$capabilities": "sort","$maxLength": 16},"ORDDAT": {"$title": "{@2566}","$shortTitle": "{@2565}","$type": "application/x-date","$isMandatory": true,"$capabilities": "sort"},"CURRENCY": {"$type": "application/x-string","$x3Format": "K:3c","$maxLength": 3,"$isExcluded": true},"CURRENCY_REF": {...},"YOHLINES": {"$type": "application/x-array","$title": "{@758}","$shortTitle": "{@758}","$item": {"$type": "application/json","$instanceUrl": "{$instanceUrl}/LINES('{$uuid}')","$properties": {"ITEM": {"$type": "application/x-string","$x3Format": "K:20c","$maxLength": 20,"$isExcluded": true},...},},"$article": {...},"$layout": {...}},"$localization": {"@100078": "Price","@10964": "Unit price",...},"$links": {...}}

In the example above:

the "$title" and "$shortTitle" information are defined as translatable texts in a "$localisation" section.
the "$article" and "$layout" section are linked to personalization and the user layout.
the YOHLINE property has a type "application/x-array". This means that it is a collection of lines. A nested "$properties" section lists all the elements of the corresponding collection.

-->

Filling the template

Once you have a template, you can set the values of your new resource into its properties.

Note: the template contains several keys prefixed by $. You do not need these keys to create a resource so you can safely delete them.

The previous step (getting a template) is optional. You can also create the JSON payload of the new resource from scratch, as long as you provide valid values for all the mandatory properties.

Creating the resource

Once you have a valid resource payload, you can create it by sending an HTTP `POST` request to the following URL:

http://myserver:myport/api1/x3/erp/MYENDPOINT/MYCLASS?representation=MYREPR.$create

Status code

If the request was successfully understood by the server, the request will return an HTTP status of 201.

Otherwise it will return an HTTP error status (4xx or 5xx).

JSON result

The POST request returns the state of the resource which has been created. This payload may be slightly different from the one you submitted because the server applied business rules defined in the class and representation before saving.

Take care that a status equal to 201 does not mean that the instance has been successfully created, but only that the class and the representations have been found and the body was properly formed. To know if the creation was successful, check if you have a `"$diagnose"` section in your feed. If this is the case, you will find the severity of the error:

"$diagnoses": [{"$severity": "error","$message": "The creation failed."}

If the creation was successful, the feed returned ends with a section like this one:

 "$links": {"$save": {"$isAction": true,"$method": "POST"}}

Testing interactively

As described in the overview, you can test interactively with a tool like Postman.

Links

Index Home