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¶
- Expect Error on server calls
- Substitution handling
- Variable handling
- Connecting as different users
- Accessing configuration and command line parameters
- Expression evaluator
- Meta data
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.
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
Into
with Delete
to get the response)
Delete DockCodesHandling.svc/PurchaseDockCodes(Contract='1',DockCode='DockA') Using getResult1 Into response
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