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 with the default settings 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.

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

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

')

The returned feed also contains a lot of metadata (properties with a name starting with $). The main information starts at the "$properties" section like in 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 "$localization" section.
  • The "$article" and "$layout" sections 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.

The template contains several keys prefixed by $. You do not need these keys to create a resource; 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 returns an HTTP status of 201.

The Location header of the response will contain the URL of the created resource.

Otherwise, it returns an HTTP error status (4xx or 5xx).

JSON result

The POST request returns the state of the created resource. This payload can differ from the one you submitted because the server applied business rules defined in the class and representation before saving.

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 OK. To know if the creation was successful, check if you have a `"$diagnose"` section in your feed. If this is the case, you can 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.