Place order using REST API

To submit an order, we need some additional data to enter in our request as seen in the placeOrderData object.

placeOrderData object

{
"ServiceUniqueId": "00000000-0000-0000-0000-000000000000",
"Quantity": 1,
"Requester": "00000000-0000-0000-0000-000000000000",
"Receiver": "00000000-0000-0000-0000-000000000000",
"CorrelationId": "00000000-0000-0000-0000-000000000000",
"FieldValues": [
    {
    "Name": "string",
    "Value": {}
    }
]
}
  1. We need the ProfileId of the user (Requester/Receiver) we want to place an order for.
  2. We need the UniqueId of the service we want to order.
  3. We need to know which fields in the order form that we want to submit data for. (Optional Only required for services that require input from form)

Lookup ProfileId for the user

Lookup a user using an email address.

$wc = Invoke-RestMethod -Uri "https://HostName:30000/Store/api/Profile?email=alice@example.com" -Headers  @{"accept"="application/json";"Authorization"="Bearer YOURKEY"} -Method Get
$wc

# print output
$wc

<# output
ProfileId          : bd576e93-d14f-4971-88ca-9033a6fb0e00 # Use this value for Requester/Receiver properties
NameId             : alice@example.com
CommonName         : alice@example.com
Email              : alice@example.com
LanguageName       : en-US
TimeZoneId         : 
CultureName        : 
IsTemporaryProfile : True
#>

Lookup UniqueId of service

Lookup the UniqueId of a service by retrieving all services, and then filter based on the identifier of the service.

$wc = Invoke-RestMethod -Uri "https://HostName:30000/StoreName/api/Service" -Header  @{"accept"="application/json";"Authorization"="Bearer YOURKEY"}
$wc | Where-Object {$_.Name -eq "Test" }

<# output
DisplayName       : @{en-US=Test; sv-SE=Test}
ShortDescription  : @{en-US=; sv-SE=}
Description       : @{en-US=; sv-SE=}
Id                : 64
UniqueId          : 6ba7d608-aa1a-47aa-9160-8f00ac0f32e6 # Use this value for ServiceUniqueId property
ProcessUniqueId   : 6f4ed4e9-b0e5-4f15-b468-97dd0602a4f4 # This value can be used to retrieve the field values for a process
Name              : Test
Owner             : 
TimeSaved         : 0
Cost              : 0,00000
MonthlyCost       : 0,00000
ImageUniqueId     : 00000000-0000-0000-0000-000000000000
Pages             : {}
Tags              : {}
AccessRoles       : {}
ServiceImages     : {}
ServiceParameters : {}
HideInServiceList : False
IsPinned          : False
ShowReceiver      : False
HideImageGallery  : False
ServiceType       : 1
LinkURL           : 
LinkOpenType      : 1
PageUniqueId      : 00000000-0000-0000-0000-000000000000
#>

Place order

Now that we have our ProfileId and UniqueId, we can place an order assuming the order we submit does not have any required form fields. An order placed via the API will bypass any data source and javascript in the form.

# Create a json to submit
$json = @'
{
    "ServiceUniqueId": "6ba7d608-aa1a-47aa-9160-8f00ac0f32e6",
    "Quantity": 1,
    "Requester": "bd576e93-d14f-4971-88ca-9033a6fb0e00",
    "Receiver": "bd576e93-d14f-4971-88ca-9033a6fb0e00",
    "CorrelationId": "00000000-0000-0000-0000-000000000000",
    "FieldValues": []
    }
'@

# Place order
$wc = Invoke-WebRequest -Uri "https://HostName:30000/StoreName/api/Order" -Header  @{"accept"="application/json";"Authorization"="Bearer YOURKEY"} -Method Post -ContentType 'application/json' -Body $json
# If successful, it should return a HTTP 201 StatusCode, in the response header, a 'Location' header points to the created order. You can use this location as a URI to request status of the ongoing order.

$wc
<# output
StatusCode        : 201
StatusDescription : Created
Content           : {}
RawContent        : HTTP/1.1 201 Created
                    Pragma: no-cache
                    Content-Length: 0
                    Cache-Control: no-cache
                    Date: Tue, 02 Feb 2021 19:27:00 GMT
                    Expires: -1
                    Location: https://zervicepoint.example.com:30000/MyStore/api/Order?orderId=1159
                    ...
Headers           : {[Pragma, no-cache], [Content-Length, 0], [Cache-Control, no-cache], [Date, Tue, 02 Feb 2021 19:27:00 GMT]...}
RawContentLength  : 0
#>

# Lookup the response of the order using location header

$order = Invoke-WebRequest -Uri $wc.Headers.Location  @{"accept"="application/json";"Authorization"="Bearer YOURKEY"}
$order | ConvertFrom-Json

<#output
OrderId            : 1159
ServiceId          : 73
ProcessId          : 73
Requester          : bd576e93-d14f-4971-88ca-9033a6fb0e00
Receiver           : bd576e93-d14f-4971-88ca-9033a6fb0e00
Parameters         : {@{OrderId=1159; Name=GivenName; Text=; Value=}, @{OrderId=1159; Name=Surname; Text=; Value=}, @{OrderId=1159; Name=Category; Text=; Value=}, @{OrderId=1159; Name=Days; Text=; Value=}...}
Events             : {@{Created=2021-02-02T19:27:06.89; Level=1; Source=1; Type=Completed; Name=CompleteOrder; Message=Order state changed to "Completed"}, @{Created=2021-02-02T19:27:05.203; Level=1; Source=2; Type=Status; Name=State; Message=Completed}, @{Created=2021-02-02T19
                     :27:05.127; Level=1; Source=2; Type=Status; Name=New State activity; Message=NULL}, @{Created=2021-02-02T19:27:03.437; Level=1; Source=2; Type=Status; Name=State; Message=Started}...}
Tasks              : {}
Status             :  
OrderDate          : 2021-02-02T19:27:00.02
Quantity           : 1
ServiceCost        : 0,00000
ServiceMonthlyCost : 0,00000
OrderState         : 4
#>

<#
OrderStates translations
0 = None
1 = Ordered
2 = Queued
3 = InProcess
4 = Completed
5 = Error
6 = Terminate
7 = Restart
8 = Waiting
9 = Rejected
#>

Place order with fields input

To submit arguments("fields") when invoking a service using the REST API. The arguments must match the element identifier of the field in the Order form. There are multiple approaches to lookup which there fields are. We'd recommend looking up the elements in the form editor, but for the purpose of exploring the rest objects we'll go through an alternative method.

# Use the ProcessUniqueId that we retrieved from the /api/Service request above.
$wc = Invoke-RestMethod -Uri "https://HostName:30000/StoreName/api/Process?UniqueId=6f4ed4e9-b0e5-4f15-b468-97dd0602a4f4" -Header  @{"accept"="application/json";"Authorization"="Bearer YOURKEY"}

# print output
$wc

<# output
IsShared                 : False
DisplayName              : @{en-US=Test}
Description              : @{en-US=}
IsCountable              : False
IsCartCompatible         : True
HideSubmitButton         : False
ProcessImage             : 
Forms                    : {@{Name=OrderForm1; DisplayName=; Fields=System.Object[]; FormType=1; ProviderMethods=System.Object[]; FormFunctions=System.Object[]}}
CreatorRoles             : {}
UseCustomOrderButtonText : False
CustomOrderButtonText    : @{en-US=}
Id                       : 64
UniqueId                 : 6f4ed4e9-b0e5-4f15-b468-97dd0602a4f4
Name                     : Test
Workflows                : {@{Id=64; Activities=System.Object[]}}
Variables                : {@{Name=Category; VariableType=String; ShouldHide=False; HideStartIndex=0; HideLength=0; IsInputParameter=False; IsRequired=False; IsOutputParameter=False; DisplayName=Category; Description=; Value=}, @{Name=GivenName; VariableType=String; ShouldHide=False;
                            HideStartIndex=0; HideLength=0; IsInputParameter=False; IsRequired=False; IsOutputParameter=False; DisplayName=GivenName; Description=; Value=}, @{Name=Level; VariableType=String; ShouldHide=False; HideStartIndex=0; HideLength=0; IsInputParameter=False; Is
                           Required=False; IsOutputParameter=False; DisplayName=Level; Description=; Value=}, @{Name=State; VariableType=String; ShouldHide=False; HideStartIndex=0; HideLength=0; IsInputParameter=False; IsRequired=False; IsOutputParameter=False; DisplayName=NewVariabl
                           e; Description=; Value=}...}
#>

From the output, we need to look into the Forms property, it will display any forms used in the process, so we will select the first Forms object from the list to select the Order form. The order form contains the fields that we can use to submit the form.

$wc.Forms[0]

# output
<#
Name            : OrderForm1
DisplayName     : @{en-US=Order form; sv-SE=Order formul?r}
Fields          : {@{Name=GivenName; DisplayName=; FieldType=1; FieldProperties=System.Object[]; Description=; IsRequired=False; IsReadonly=False; IsHidden=False; LineBreak=False; BoundTo=GivenName; OnLoad=; OnChange=; OnSubmit=; Fields=System.Object[]; FieldSize=3}, @{Name=Surname; 
                  DisplayName=; FieldType=1; FieldProperties=System.Object[]; Description=; IsRequired=False; IsReadonly=False; IsHidden=False; LineBreak=False; BoundTo=Surname; OnLoad=; OnChange=; OnSubmit=; Fields=System.Object[]; FieldSize=3}, @{Name=Category; DisplayName=; FieldT
                  ype=4; FieldProperties=System.Object[]; Description=; IsRequired=False; IsReadonly=False; IsHidden=False; LineBreak=False; BoundTo=Category; OnLoad=; OnChange=; OnSubmit=; Fields=System.Object[]; FieldSize=3}}
FormType        : 1
ProviderMethods : {}
FormFunctions   : {}
#>

In the order form object, we can lookup the values in the Fields property.

$wc.Forms[0].Fields
<# output

Name            : GivenName
DisplayName     : @{en-US=First name; sv-SE=F?rnamn}
FieldType       : 1
FieldProperties : {@{Id=5874; Name=defaultvalue_en-US; Value=}, @{Id=5875; Name=validationmessage_en-US; Value=}, @{Id=5876; Name=validationtype; Value=0}, @{Id=5877; Name=validationpattern; Value=}}
Description     : @{en-US=; sv-SE=}
IsRequired      : False
IsReadonly      : False
IsHidden        : False
LineBreak       : False
BoundTo         : GivenName
OnLoad          : 
OnChange        : 
OnSubmit        : 
Fields          : {}
FieldSize       : 3

Name            : Surname
DisplayName     : @{en-US=LastName; sv-SE=Efternamn}
FieldType       : 1
FieldProperties : {@{Id=5878; Name=defaultvalue_en-US; Value=}, @{Id=5879; Name=validationmessage_en-US; Value=}, @{Id=5880; Name=validationtype; Value=0}, @{Id=5881; Name=validationpattern; Value=}}
Description     : @{en-US=; sv-SE=}
IsRequired      : False
IsReadonly      : False
IsHidden        : False
LineBreak       : False
BoundTo         : Surname
OnLoad          : 
OnChange        : 
OnSubmit        : 
Fields          : {}
FieldSize       : 3

Name            : Category
DisplayName     : @{en-US=Category; sv-SE=Kategori}
FieldType       : 4
FieldProperties : {@{Id=5882; Name=dropdownItems_[0]_id; Value=1}, @{Id=5883; Name=dropdownItems_[0]_value; Value=Info}, @{Id=5884; Name=dropdownItems_[0]_selected; Value=False}, @{Id=5885; Name=dropdownItems_[0]_cost; Value=0}...}
Description     : @{en-US=; sv-SE=}
IsRequired      : False
IsReadonly      : False
IsHidden        : False
LineBreak       : False
BoundTo         : Category
OnLoad          : 
OnChange        : 
OnSubmit        : 
Fields          : {}
FieldSize       : 3

#>

In the output above we'll retrieve the identifer from the property Name. This leaves us with:

  • GivenName
  • Surname
  • Category

As the Category identifer is a static dropdown with additional items, we must lookup those as well to identify valid values to submit.

($wc.Forms[0].Fields.Where({$_.FieldType -eq 4 })).FieldProperties

<# output
  Id Name                                  Value
  -- ----                                  -----
5882 dropdownItems_[0]_id                      1
5883 dropdownItems_[0]_value                Info
5884 dropdownItems_[0]_selected            False
5885 dropdownItems_[0]_cost                    0
5886 dropdownItems_[0]_monthlyCost             0
5887 dropdownItems_[0]_label_en-US Informational
5888 dropdownItems_[0]_label_sv-SE   Information
5889 dropdownItems_[1]_id                      2
5890 dropdownItems_[1]_value             Warning
5891 dropdownItems_[1]_selected            False
5892 dropdownItems_[1]_cost                    0
5893 dropdownItems_[1]_monthlyCost             0
5894 dropdownItems_[1]_label_en-US       Warning
5895 dropdownItems_[1]_label_sv-SE       Varning
5896 dropdownItems_[2]_id                      3
5897 dropdownItems_[2]_value               Error
5898 dropdownItems_[2]_selected            False
5899 dropdownItems_[2]_cost                    0
5900 dropdownItems_[2]_monthlyCost             0
5901 dropdownItems_[2]_label_en-US         Error
5902 dropdownItems_[2]_label_sv-SE           Fel
5903 isRestricted                           True
5904 isSearchable                          False
5905 isMultiSelect                         False
5906 isDynamicBind                         False
5907 allowClear                            False
5908 placeholder_en-US                          
5909 useClientCache                         True
5910 useDynamicDebounce                    False
5911 minimumSearchLength                       1
5912 dataSource                                 
#>

From the output above, we can lookup the dropdown items and lookup the available value that we can use as value for the Category field.

  • Info
  • Warning
  • Error

Now that we've have all the info we need, lets build our request object

$json = @'
{
  "Quantity": 1,
  "ServiceUniqueId": "6ba7d608-aa1a-47aa-9160-8f00ac0f32e6",
  "Requester": "bd576e93-d14f-4971-88ca-9033a6fb0e00",
  "Receiver": "bd576e93-d14f-4971-88ca-9033a6fb0e00",
  "CorrelationId": "00000000-0000-0000-0000-000000000000",
  "FieldValues": [
    {
        "Name": "GivenName",
        "Value": "Hazim"
    },
    {
        "Name": "Surname",
        "Value": "Kaiser"
    },
    {
        "Name": "Category",
        "Value": "Info"
    }
  ]
}
'@

$wc = Invoke-WebRequest -Uri "https://HostName:30000/StoreName/api/Order" `
-Headers @{"accept"="application/json";"Authorization"="Bearer YOURKEY"} `
-Method Post `
-Body $json `
-ContentType 'application/json'