Scripted Web Operations

Last updated
Save as PDF

Overview

The Solution Builder provides an intuitive way to create custom business logic using Workflows, which are executed asynchronously. However, this approach is unsuitable when custom logic must execute synchronously, with immediate results—such as in user interface operations or third-party integrations.

For such cases, custom logic can be developed as a Web Service, deployed, and registered in Solution Builder, which requires development expertise. Alternatively, the same functionality can be achieved using a PowerShell script declared as a Scripted Web Service in the Web Service Repository.

Usage

The Scripted Web Operation behaves similarly to a classical Web Service based on the .NET type. It can be called externally over a REST request. By running the “Code Example” action, users can generate instructions on how to implement such a request in C# or JavaScript. Additionally, Scripted Web Operations can be seamlessly integrated into Layout Designer as an “Additional Data Source” based on the Service Operation or configured as a Submit operation for a Wizard.

Managing Scripted Web Operations

Search and List

Use the Search Filter “Scripted Operations” under Administration → Web Services to easily filter all Web Services that include a Scripted Web Operation.

The list with applied filter shows all Web Services that have Scripted Web Operations. Click on the Web Service for details. The Web Service preview additionally marks Scripted Web Operations as Script, for instance:

Scripted Operations.png

Modify Web Service: Add Scripted Web Operation

A Scripted Web Operation can be added to an existing Web Service using the “Add Operation” action and later modified using “Edit Operation”.

Add Scripted Web Operation

To add Scripted Web Operation, in Administration application → Integration → Web Services search for the necessary Web Service that should be extended, click on the Web Service, and on the Preview click Show More Actions and select Add Operation:

WebAPI Service Add operation1.png

A new Web Service Operation form requires the following information:

Edit Scripted Web Operation.png

Name: A user-friendly name for the Web Operation.
Method: Defines the HTTP request method (e.g., GET, POST, PUT, DELETE). More details can be found at MDN Web Docs.
Route Template: Specifies the endpoint URL for the Web Operation.
The specified Route Template is added to the extended WebAPI Service Endpoint, for instance, {id}/entradetails Route Template is shown as follows when saved:

The final URL follows this structure:
```
https://<server_url>/m42services/api/<route_template>
```
The Route Template also determines where parameters are placed in the URL path.
Return Type: Defines the data type of the Web Operation’s response. If the response is an array, enable the “Is Array” option.
Script: A PowerShell script that defines the custom logic executed when the Web Operation is invoked. For details on how to configure the script and examples, see Script Parameters and Configuration section below.
Documentation: a plain text description of the Scripted Web Operation that will be shown on the WebAPI Service Preview page.

Edit Scripted Web Operation

To edit the Scripted Web Operation, in the Administration application → Integration → Web Services, search for the WebAPI Service with Scripted Web Operations and click on the route template name:

Edit Scripted Web Operation example.png

On the operation preview page, run the Edit Operation action to modify the configuration:

Scripted Web Operation Edit Operation action.png

Edit Operation action is available only for the Web Operations marked as Script.

Script parameters and configuration

Parameters are defined within the Script section and are specified using the param() statement.

Data Types

Supported parameter data types include:

string, Guid, bool, int, double, long, decimal, DateTime, Object

Parameter Binding

The system provides several attributes to define parameter value sources:

Use the param() statement to specify input parameters, their types, and sources.
Use the return statement to define the Web Operation’s response.
Utilize the Private SDK API and global PowerShell variables to implement widely used functions within the custom logic.

Parameters

[QueryString] – Reads the parameter value from the query string. If no explicit binding is defined, this is the default behavior.

Example: /api/custom_service?param1={param1_value}
[Path] – Extracts the parameter value from the URI. The parameter must be explicitly defined in the Route Template.

Example:
- Route Template: custom_service/{id}/add
- Parameter Definition: [Path][guid] $id
[Body] – Reads the parameter from the request body. This binding is only applicable for POST or PUT requests.

Examples

Case 1: Get User details directly from EntraID

Get the user details directly from EntraID:

Method: GET
Route Template: {id}/entradetails
Return Type: Object

param(
   [path]
   [guid]$id
)


$M42_Log.Info("Get user details from EntraID, user id {0} ", $id)
$connectionId = $M42_DatabaseProvider.GetData("SPSGenericConnectorConfigurationClassAzureAD", "ServiceConnection.[Expression-ObjectID] as ServCon", "T(SPSGenericConnectorConfigurationClassBase).Enabled = 1", $null).Rows[0]["ServCon"];

$userId = $M42_DatabaseProvider.GetData("SPSUserClassBase", "MailAddress", "[Expression-ObjectID] = '$id'", $null).Rows[0]["MailAddress"];

$authInfo = $M42_ServiceConnection.GetAuthData([System.guid]$connectionId)

# Set Authorization Header
$Headers = @{
    Authorization = $authInfo.AuthHeader
    "Content-Type" = "application/json"
}

# Make the API Request
$GraphUrl = "https://graph.microsoft.com/v1.0/users/$($userId)?`$select=displayName,mail,preferredLanguage"

$UserDetails = Invoke-RestMethod -Uri $GraphUrl -Headers $Headers -Method Get

return @{
   userid = $userId
   lang = $UserDetails.preferredLanguage
}

Case 2: Set User Preferable Language in EntraID

Set the preferable language for user directly in Entra ID

Method: GET
Route Template: {id}/update_aad
Return Type: None

param(
   [path][guid]$id,
   [querystring][string]$preferredLanguage
)

$M42_Log.Info("Update user details from EntraID, user id {0} ", $id)
$connectionId = $M42_DatabaseProvider.GetData("SPSGenericConnectorConfigurationClassAzureAD", "ServiceConnection.[Expression-ObjectID] as ServCon", "T(SPSGenericConnectorConfigurationClassBase).Enabled = 1", $null).Rows[0]["ServCon"];
$userId = $M42_DatabaseProvider.GetData("SPSUserClassBase", "MailAddress", "[Expression-ObjectID] = '$id'", $null).Rows[0]["MailAddress"];

$authInfo = $M42_ServiceConnection.GetAuthData([System.guid]$connectionId)
# Set Authorization Header
$Headers = @{
    Authorization = $authInfo.AuthHeader
    "Content-Type" = "application/json"
}
$Body = @{
    preferredLanguage = $preferredLanguage
} | ConvertTo-Json -Depth 10
# Make the API Request
$GraphUrl = "https://graph.microsoft.com/v1.0/users/$($userId)/"
Invoke-RestMethod -Uri $GraphUrl -Headers $Headers -Method Patch -Body $Body -ContentType "application/json"

Case 3: Service Operation for UUX Action

The Solution Builder allows a Service Operation to be executed immediately upon triggering a UUX Action, without requiring additional input via a wizard. Only operations with a strict input contract can be used for this purpose.

The following example demonstrates how such an operation can be defined using a Scripted Web Service.

Operataion method: POST
Script:

param(
 [Body][object]$request
)

$context = $request[0]
$M42_Log.Info("Context Type Name $($context["TypeName"].ToString())" )

foreach ($item in $context["ObjectIds"]) {
    $M42_Log.Info( "Object Id $($item.ToString())" )
}
return $request