Skip to content

Commands reference

Script-A-Rest primarily includes commands to perform server calls, handle variables and orchestrate scripts. It also includes few other useful utilities and commands for performing assertions.

Commands

Commands are structured as one line with command and arguments with an optional JSON block.

Commands must begin at first position on a line. Command keywords are case insensitive. So Get SomeSvc.svc/SomeEntitySet is the same as Get SomeSvc.svc/SomeEntitySet.

Generally URLs, JSON payloads and variable references are case sensitive. So Get SomeSvc.svc/SomeEntitySet is NOT the same as Get someSvc.svc/someentityset.

Line comments can begin either with // or --. Comments be on first position on line. Comments after commands does not work.

Data types

Variables in Script-A-Rest are either basic types like string, int, double, boolean, DateTime or compound JSON types, i.e. containing an JSON object of any size and/or complexity.

JSON only supports string, numeric, boolean and null basic values. Complex JSON values are objects or arrays. Due to lack of JavaScript number precision, FndODataProvider and IFS Cloud Web Framework serializes numbers as strings (using IEEE 754 header). Script-A-Rest sends requests with IEEE 754 header and therefore any JSON values sent must be quoted as strings. Eg.,

{
    "pi": "3.14"
}

Available Commands

Server calls

Script variable handling

Calling other scripts

Other commands

Other references

Post

Call URL with HTTP POST

Post can be done conditionally by using then When keyword.

(Also see the alternatives Action and Create)

Syntax

Post {ExpectFail} [URL path to service] {Using variableWithEtag} {Into [resultVariable] } {When [condition]}
JSON Object Body

Example

Post DockCodesHandling.svc/PurchaseDockCodes Into createResult1
{
    "Contract": "1",
    "DockCode": "DockA",
    "Description": "Main Gate"
}

Into section and variable is optional. If specified data returned from server will be placed here.

Post DockCodesHandling.svc/PurchaseDockCodes
{
    "Contract": "1",
    "DockCode": "DockA",
    "Description": "Main Gate"
}

Using section is optional and needed when calling actions requiring ETag, eg entity-bound actions. When Using is used, Into is mandatory

Post DockCodesHandling.svc/PurchaseDockCodes('DockA')/Ifsapp.DockCodesHandling.Release Using getResult1 Into createResult1
{
    "Extraparams": "1",
}

Sometimes a call shouldn't be executed unless a certain condition is met.

Post DockCodesHandling.svc/PurchaseDockCodes('DockA')/Ifsapp.DockCodesHandling.Release Using getResult1 Into createResult1 When 1==1
{
    "Extraparams": "1",
}

See ExpectFail on server calls for details about ExpectErrors keyword

Get

Call URL with HTTP GET verb.

Get can be done conditionally by using then When keyword.

Syntax

Get {ExpectFail} [URL path to service] Into [resultVariable] When [condition]

Examples (Assuming result of Get command will be used in the following command(s), here CopyJson.)

Example 1

Get DockCodesHandling.svc/PurchaseDockCodes(Contract='1',DockCode='A') Into getResult
CopyJson Description Using getResult Into response 

Example 2

Get DockCodesHandling.svc/PurchaseDockCodes(Contract='1',DockCode='A') Into getResult When 1==1
CopyJson Description Using getResult Into response When 1==1 

Example 3

ApplyJson Into getResult
{
}
Get IsoUnitsOfMeasureHandling.svc/IsoUnitSet(UnitCode='{$input.UnitCode}') Into getResult When 1==1
CopyJson UsedInAppl Using input into response When 1==1 && getResult.UserDefined==false

Into section and variable is mandatory and data returned from server will be placed here.

When section is optional. If specified and condition is met, data returned from the server will be placed in Into variable.

See ExpectFail on server calls for details about ExpectErrors keyword

Query

Call URL with HTTP GET verb with options Select, OrderBy and Filter

Syntax

Query {ExpectFail} [URL path to service] {Select "Attr1,Attr2"} {OrderBy "Attr1 desc,Attr2"} {Filter With Json} Into [resultVariable] When [condition]

Select

The Select query option allows the clients to requests a limited set of properties for each entity.

OrderBy

The OrderBy query option allows clients to request resources in either ascending order or descending order using desc.

Filter

The Filter query option allows clients to filter a collection of resources that are addressed by a request URL. The expression specified for the filter is evaluated for each resource in the collection, and only items where the expression evaluates to true are included in the response.

Filter With Json Expressions are evaluated with AND between different attributes and OR within an attribute. Default operator is equal.

A Json Filter in it's simplest form: Returns items for expression Contract=A

{
   "Contract": "A"
}

A Json Filter with Multiple attributes: Returns items for expression ((OrderNo=1 OR OrderNo=2) AND (Contract=A OR Contract=B OR Contract=C))

{
   "OrderNo": "1;2",
   "Contract": "A;B;C"
}

You can use variables like "OderNo" : "{$input.OrderNo}" inside the Json for the Filter query option. However note that only $ and # works for automatic quotation of string values. Using % does not work due to defect TAR-252.

Filter Operators

Default operator is equal if no operator is specified.

Supported operators:

  • >= Greater Than Or Equal
  • > Greater Than
  • <= Less Than Or Equal
  • < Less Than
  • != Not Equal
  • = Equal

A Json Filter with operator: Returns items for expression OrderNo>=5

{
   "OrderNo": ">=5"
}

Filter Data Types

String

{
   "Attribute1": "5",
   "Attribute2": "5;7;10"
}

Number

{
   "Quantity1": 5,
   "Quantity2": {"Number": "5;7;10"}
}

Enumeration

{
    "Enumeration1": {"Enumeration": {"Enum.SomeEnum": "Value1;Value2"}}
}

Date Can either be a single day or a range.

{
    "Date1": {"Date": "2020-12-01"},
    "Date2": {"Date": "2020-12-01;2020-12-23"}
}

DateTime
Can either be a single day or a range.
{ "DateTime1": {"DateTime": "2020-12-01"}, "DateTime2": {"DateTime": "2020-12-01;2020-12-23"} }

Filter Examples

Example 1

Query ShopOrdersHandling.svc/ShopOrds Select "OrderNo,Contract" OrderBy "Contract,OrderNo desc" Filter With Json Into queryResult
{
   "Contract": "MF-S1",
   "OrderNo": ">=204129",
   "EffPhaseInDate": {"Date": "2021-01-07;2021-01-08"}
}

Patch

Change an entity URL (HTTP PATCH). Requires an object retrieved either by a Get or Create command.

Patch can be done conditionally by using then When keyword.

(Also see the Modify which is an alias for Patch)

Syntax

Patch {ExpectFail} [URL path to service] Using [variable] Into [resultVariable] When [condition]
JSON Object Body

Example (assuming result retrieved earlier, see Get or Create)

Patch DockCodesHandling.svc/PurchaseDockCodes(Contract='1',DockCode='DockA') Using getResult1 Into patchResult1 When 1==1
{
    "Description": "Changed description"
}

Only the attributes changed needs to be provided in JSON Object body. Not sent attributes will be unchanged.

Flow for Modify * Retrieve @odata.etag from provided variable (getResult1) * Perform PATCH call to service * Retrieve result from server and place it in patchResult1.

This flow makes it possible to perform subsequent modify calls

See ExpectFail on server calls for details about ExpectErrors keyword

Upsert Functionality using Patch

A record can be inserted (if it does not already exist), or modified using the Patch command.

An empty Json object can be used instead of the results retrieved from Get or Create calls as shown in the example below

ApplyJson Into result
{
}
Patch DockCodesHandling.svc/PurchaseDockCodes(Contract='1',DockCode='DockA') Using result Into patchResult1
{
    "Contract": "1",
    "Description": "Description",
    "DockCode": "DockA"
}

PatchBlob

Change an entity URL (HTTP PATCH) with the purpose to modify an Edm.Stream attribute (eg picture or document). Requires an object retrieved either by a Get or Create command.

PatchBlob can be done conditionally by using then When keyword

(Also see the ModifyBlob which is an alias for Patch)

Syntax

PatchBlob {ExpectFail} [URL path to service] Using [variable] When [condition]
{
    "fileReference": "[aFileReference]"
}

Example (assuming result retrieved earlier, see Get or Create)

PatchBlob PersonHandling.svc/PersonInfoSet(PersonId='TOST')/PersonImage Using personInfo1 When 1==1
{
    "fileReference": ".\\Tony-Stark.jpg"
}

Body must contain the only attribute fileReference with a value containing the file name (and optional file path). If no absolute path is specified, path is determined relative to the script location (folder).

Flow for Modify * Retrieve @odata.etag from provided variable (getResult1) * Perform PATCH call to service PATCH call will upload data as application/octet-stream and send an X-IFS-Content-Disposition header with file name * Since server sends an empty response, the provided variable (getResult1) will be empty and cannot be used for subsequent calls.

See ExpectFail on server calls for details about ExpectErrors keyword

Delete

Delete an entity URL (HTTP DELE). Requires an object retrieved either by a Get or Create command

Delete can be done conditionally by using the When keyword.

Syntax

Delete {ExpectFail} [URL path to service] Using [variable] When [condition]

Example 1 (assuming result retrieved earlier, see Get or Create)

Delete DockCodesHandling.svc/PurchaseDockCodes(Contract='1',DockCode='DockA') Using getResult1
Example 2 (Using Into with Delete to get the response)
Delete DockCodesHandling.svc/PurchaseDockCodes(Contract='1',DockCode='DockA') Using getResult1 Into response
Example 3 (Using When as sometimes a call shouldn't be executed unless a certain condition is met)
Delete DockCodesHandling.svc/PurchaseDockCodes(Contract='1',DockCode='DockA') Using getResult1 When 1==1

No body payload should be sent. Only key and etag (objversion) is needed for delete.

Flow for Modify * Retrieve @odata.etag from provided variable (getResult1) * Perform Delete call to service * No result from server. Variable is unchanged

See ExpectFail on server calls for details about ExpectErrors keyword

Batch

Batch a number of HTTP request methods into one call. Sometimes it's necessary to perform a number of requests within the same session, then Batch can be used.

Syntax

Batch {ExpectFail} [URL path to service] {Using variableWithEtagsArray} {Into [resultVariableArray] } {When [condition]}
JSON Array Body

Example

Batch SalesRuleHandling.svc Into myBatch
[
    {"POST ValidateCondition":
    {"Init":true}},
    {"POST ConfigSalesRuleSet(SalesRuleId={$myId})/ConditionsArray":
    {
        "SalesRuleId":{%myId},
        "Value":"CNV1",
        "CompareValue":"5",
        "ConfigRelationalOperator":"EqualTo",
        "CompareConditionType":"Value",
        "ConditionType":"CharValue",
        "ConfigValueType":"VARIABLEVALUE"
    }},
    {"POST ConfigSalesRuleSet(SalesRuleId={$myId})/ConditionsArray":
    {
        "SalesRuleId":{%myId},
        "Value":"CNV1",
        "CompareValue":"6",
        "ConfigRelationalOperator":"EqualTo",
        "ConfigLogicOperator":"And",
        "CompareConditionType":"Value",
        "ConditionType":"CharValue",
        "ConfigValueType":"VARIABLEVALUE"
    }},
    {"POST ValidateCondition":
    {"Init":false}}
]

Into section is optional. If specified, data returned from the server will be placed in the succeeding variable. For Batch calls it will stored as an array of responses. One array object for each call in the batch.

Using section is optional and needed when calling actions requiring ETag, eg entity-bound actions. When calling Batch with Using it shall be on array format and the ETag corresponding to the n'th call should be located in the n'th object in the array.

Batch SalesRuleHandling.svc Using myBatch.value Into myBatch2
[
    {"POST ValidateCondition":
    {"Init":true}},
    {"PATCH ConfigSalesRuleSet(SalesRuleId={$myId})/ConditionsArray(SalesRuleId={$myId},SalesRuleConditionId={$myBatch.value.Items(1).SalesRuleConditionId})":
    {"CompareValue":"7"}},
    {"PATCH ConfigSalesRuleSet(SalesRuleId={$myId})/ConditionsArray(SalesRuleId={$myId},SalesRuleConditionId={$myBatch.value.Items(2).SalesRuleConditionId})":
    {"CompareValue":"8"}},
    {"POST ValidateCondition":
    {"Init":false}}
]

Batch can be done conditionally by using the When keyword. Sometimes a call shouldn't be executed unless a certain condition is met.

Batch SalesRuleHandling.svc Using myBatch.value Into myBatch2 When 1==1
[
    {"POST ValidateCondition":
    {"Init":true}},
    {"PATCH ConfigSalesRuleSet(SalesRuleId={$myId})/ConditionsArray(SalesRuleId={$myId},SalesRuleConditionId={$myBatch.value.Items(1).SalesRuleConditionId})":
    {"CompareValue":"7"}},
    {"PATCH ConfigSalesRuleSet(SalesRuleId={$myId})/ConditionsArray(SalesRuleId={$myId},SalesRuleConditionId={$myBatch.value.Items(2).SalesRuleConditionId})":
    {"CompareValue":"8"}},
    {"POST ValidateCondition":
    {"Init":false}}
]

See ExpectFail on server calls for details about ExpectErrors keyword

JSON Array Body

The JSON Array Body consists of a number of JSON Objects each representing a request. Each JSON Object has key: "[HTTP Request method] [relative URL path to service]" value: [JSON Object body].

[
    {"POST ValidateCondition":
    {"Init":true}}
]

Eval

Evaluate expression (in C#) syntax and place result in variable. Evaluation can be done conditionally by using then When keyword

Eval [expression] Into [variable] {When [condition]}

Expression evaluator is using the "DynamicExpresso" library. See more info here.

Examples

Store constant string "1" in s1.

Eval "1" Into s1

Add 10 + 15 and store result (25) in i2