Skip to main content

Request body options

The request body is a JSON object that contains three root-level fields:

  1. data

  2. projectArguments

  3. options

The data and projectArguments fields are described in Using a Studio app's API > The request body.

This topic covers the options field only. This field is optional and is usually omitted. The field includes settings that allow you to configure the runtime behavior for your project. The settings are:

  1. nullValueBehaviour defines what value to insert when an ATL statement returns an undefined or null result. You can give one of the following values:

    1. ERROR_IF_ANY_NULL causes the generation of a runtime error. This error will be present in the errorType and errorMessage fields in the response object.

    2. SHOW_BLANK inserts a blank value (empty string).

    3. SHOW_IDENTIFIER inserts the original ATL syntax into the result so you can see the ATL content that led to the problem. This is the default behavior.

  2. contentOutputFormat is optional and specifies whether the output text should be in HTML format or plain text format:

    1. HTML = HTML format (default).

    2. TEXT = plain text format.

  3. contentLineEnding is optional and specifies line ending character(s) to be inserted in plain text format:

    1. The default is the line end characters for a carriage return and newline (i.e. "\r\n") but you can specify a single character (e.g. "\n") if you prefer. The character(s) you specify are inserted twice at paragraph breaks (e.g. "\r\n\r\n").

  4. contentLineLength is optional and specifies the maximum line length for insertion of line breaks in plain text format. Words are not broken across line breaks; consequently, some lines may be shorter than the maximum length:

    1. An integer denoting the maximum length for a line line (e.g. 20). The default is for no maximum line length, meaning no line breaks are inserted.

  5. templateFragment is optional and allows you to call a specific ATL script (but not a user-defined function) or ATL fragment. It can include the following settings:

    1. fragmentName enables you to call a specific named ATL script. For instance, a call to the CapitalCity subscript in the "Describe Row in Context" sample project will output the text generated from that subscript only.

    2. selectionIndex is used with fragmentName and selectionLength to produce a substring of the output text. selectionIndex is the start index of the substring; an error occurs if it is outside the range of the script.

    3. selectionLength is used with fragmentName and selectionIndex to produce a substring of the output text. selectionLength is the length of the substring; an error occurs if it goes past the end of the script.

    4. fragmentText allows you to call the API with a string of ATL. For example, if you input the string This report describes Australian states: [[RowNames]]. in a call to the Describe Row in Context" sample project, the output is:

      This report describes the Australian states: New South Wales, Victoria, Queensland, Western Australia, South Australia, Tasmania, the Australian Capital Territory and the Northern Territory.

      In a body request, this would like this:

      "fragmentText": "This report describes Australian states: [[RowNames]]

      Note: fragmentText should not be used together with fragmentName.

Example

The following request body works with a published version of the "Describe Each Row" sample project.

This example uses all five of the main settings mentioned above.

{
 "data": [{
    "id": "Primary",
    "type": "1d",
    "dataSet": [
	["State", "Premier", "Party", "Terms", "StateLandArea", "StatePop2010", "StatePop2016", "Capital", "CapitalPop2010", "CapitalPop2016"],
	["Victoria", "Daniel Andrews", "ALP", "1", "227,416", "5,547,500", "5,938,100", "Melbourne", "3,953,939", "4,353,514"],
	["New South Wales", "Gladys Berejiklian", "Liberal", "1", "800,641", "7,238,800", "7,618,200", "Sydney", "4,183,471", "4,526,479"],
	["Queensland", "Annastacia Palaszczuk", "ALP", "1", "1,730,647", "4,516,400", "4,779,400", "Brisbane", "2,019,074", "2,209,453"],
	["Western Australia", "Colin Barnett", "Liberal", "2", "2,529,875", "2,296,400", "2,591,600", "Perth", "1,723,218", "1,958,912"],
	["South Australia", "Jay Weatherill", "ALP", "2", "983,482", "1,644,600", "1,698,600", "Adelaide", "1,225,668", "1,288,681"],
	["Tasmania", "Will Hodgman", "Liberal", "1", "68,401", "507,600", "516,600", "Hobart", "203,446", "209,254"],
	["Australian Capital Territory", "Andrew Barr", "ALP", "1", "2,358", "358,900", "395,200", "Canberra", "355,596", "381,488"],
	["Northern Territory", "Michael Gunner", "ALP", "1", "1,349,129", "229,700", "244,600", "Darwin", "112,987", "123,396"]
     ]
  }],
  "options": {
      "nullValueBehaviour": "SHOW_IDENTIFIER",
      "contentOutputFormat": "TEXT",
      "contentLineEnding": "\n",
      "contentLineLength": 50,
      "templateFragment": {
            "fragmentName": "Main"
	     }
	}
}

Note

Note how the fragmentName setting is entered as a key within the templateFragment setting. All templateFragment settings must be entered this way.

© Arria Data2Text Limited