Script Execute Operation

Last modified 13 Mar 2024 13:32 +01:00

Table of Contents

Description
Request
Access Authorization
Model Authorization
Examples
See Also

Description

Remote procedure call (RPC) type of request which is specifically used for script execution. The script which should be executed is a part of the request body.

Request

For the request you need to use the HTTP POST method.

Execute Script operation using HTTP POST

POST http://localhost:8080/midpoint/ws/rest/rpc/executeScript

Headers

Regarding authorization type, the "Basic" Authorization header should be used.

Authorization header example replace {Base64EncodedCredentials} with the encoded credentials

Authorization: Basic {Base64EncodedCredentials}

To specify the provided content type, please use the "Content-Type" header payload in the body:

Content type header example, other media types are supported as well

"Content-Type: application/json"

You might need to specify the accepted type of content in case you are interested in a format different from xml (default):

Accept type header example, other media types are supported as well

"Accept: application/json"

For supported media types please refer to the following section of the documentation

Supported Media Types

Body

The body should contain a payload consisting of a ExecuteScriptType type of object containing. Please have a look on the examples on this page for a sample of the object in the body.

Options

There are no supported operation options for this type of operation.

Response

Error code	Meaning
1xx	Information. Stay tuned, operation is in progress.
2xx	Success. Operation finished successfully. There are two custom codes: 250 for partial error which means that during processing some error occurred but some changes was executed. 240 for handled error which means that there was originally error, but midPoint was able to fix this using its consistency mechanism. In this two cases, midPoint returns the OperationResult where there details of executed operations can be found.
3xx	Redirection or "in progress". This is returned mostly to indicate two cases: Operation has finished, but the results are not in this resource. Redirection is issues to point the client to the results. Typical example is creation of an object with POST to a collection web resource. In this case a new object is created, new URI is assigned and the client is redirected to this URI. Retrieving that URI provides created object and 200 status code, indicating that the operation is finished. Operation is in progress (asynchronous operation). In this case midPoint API redirects the client to a task object that can be used to track progress of the operation.
4xx	Client errors. The client has sent request that cannot be processed. This indicates usual situation that are well handled by the midPoint code. Maybe the client request to create conflicting object, delete non-existent object, modification that violates the schema and so on. The OperationResult structure is usually provided in the response to provide more details about the situation.
5xx	Server errors. Situations that the server cannot handle and where the cause is unknown. This usually means bugs in the code, insufficient resources such as RAM or disk space, unforeseen failures in the infrastructure and so on. The OperationResult structure might or might not be provided in this case. Some errors are so severe that the structured error information might not be available.

Error code

Meaning

1xx

Information. Stay tuned, operation is in progress.

2xx

Success. Operation finished successfully. There are two custom codes:

250 for partial error which means that during processing some error occurred but some changes was executed.
240 for handled error which means that there was originally error, but midPoint was able to fix this using its consistency mechanism.

In this two cases, midPoint returns the OperationResult where there details of executed operations can be found.

3xx

Redirection or "in progress". This is returned mostly to indicate two cases:

Operation has finished, but the results are not in this resource. Redirection is issues to point the client to the results. Typical example is creation of an object with POST to a collection web resource. In this case a new object is created, new URI is assigned and the client is redirected to this URI. Retrieving that URI provides created object and 200 status code, indicating that the operation is finished.
Operation is in progress (asynchronous operation). In this case midPoint API redirects the client to a task object that can be used to track progress of the operation.

4xx

Client errors. The client has sent request that cannot be processed. This indicates usual situation that are well handled by the midPoint code. Maybe the client request to create conflicting object, delete non-existent object, modification that violates the schema and so on. The OperationResult structure is usually provided in the response to provide more details about the situation.

5xx

Server errors. Situations that the server cannot handle and where the cause is unknown. This usually means bugs in the code, insufficient resources such as RAM or disk space, unforeseen failures in the infrastructure and so on. The OperationResult structure might or might not be provided in this case. Some errors are so severe that the structured error information might not be available.

Status codes and the indication of errors and asynchronous processing applies uniformly to all midPoint web resources (both RESTful and RPC).

Responses In Case Of Success

200 OK, ExecuteScriptResponseType returned in the body
201 Created, Location set to point to the newly created Task object. Only applicable is asynchronous=true parameter is used.
240 Handled error, OperationResult is returned in the body
250 Partial error, OperationResult is returned in the body

Access Authorization

The interface authorization needed for executing this type of request. The authorization is needed to access the specific part of the interface. For more information please see this page.

http://midpoint.evolveum.com/xml/ns/public/security/authorization-rest-3#executeScript

Model Authorization

The model authorization for the specific action. This authorization is needed to request/execute the concrete action. The examples are usually quite broad, and the actions can be additionally specified for a more fine-grained authorization. For more information please see this page.

The following authorization is a buld authorization which is quite broad, please see the following documentation for how to specify a more concrete authorization.

http://midpoint.evolveum.com/xml/ns/public/security/authorization-bulk-3#all

Examples

In our examples we are authenticating with the credentials, name "administrator" and password "y0uR_P455woR*d" on a localhost instance running on port 8080.

For some help regarding the REST examples please see this link:

How to use MidPoint REST examples

Execute script with procedure call to recompute object on input

curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X POST http://localhost:8080/midpoint/ws/rest/rpc/executeScript \
-v \
--data-binary @./samples/rest/rpc-recompute-input-filter.json

Show data source example for "Execute script with procedure call to recompute object on input" | GitHub

{
  "@ns" : "http://midpoint.evolveum.com/xml/ns/public/model/scripting-3",
  "executeScript" : {
    "pipeline" : [ {
      "@element" : "action",
      "type" : "resolve"
    }, {
      "@element" : "action",
      "type" : "recompute"
    } ],
    "input" : {
      "value" : {
        "@type" : "c:ObjectReferenceType",
        "oid" : "a9885c61-c442-42d8-af34-8182a8653e3c",
        "type" : "UserType"
      }
    },
    "options" : {
      "continueOnAnyError" : "true"
    }
  }
}

The response is an HTTP 200 code in case of success with a response body.

Example Output of "Execute script with procedure call to recompute object on input" example

The example is simplified, some properties were removed to keep the example output "short". This example does not contain all possible properties of this object type.

{
  "@ns" : "http://prism.evolveum.com/xml/ns/public/types-3",
  "object" : {
    "@type" : "http://midpoint.evolveum.com/xml/ns/public/common/api-types-3#ExecuteScriptResponseType",
    "output" : {
      "dataOutput" : {
        "item" : [ {
          "value" : {
            "@type" : "c:UserType",
            "oid" : "a9885c61-c442-42d8-af34-8182a8653e3c",
            "version" : "16",
            "name" : "Jack",
            "metadata" : {},
            "operationExecution" : [ {}, {}],
            "assignment" : [ {}, {} ],
            "iteration" : 0,
            "iterationToken" : "",
            "roleMembershipRef" : [ {}, {} ],
            "activation" : {},
            "emailAddress" : "jack@evolveum.com",
            "credentials" : {}
          },
          "result" : {
            "operation" : "com.evolveum.midpoint.model.impl.scripting.BulkActionsExecutor.process",
            "status" : "success",
            "importance" : "normal",
            "end" : "2024-02-19T12:05:26.393+01:00",
            "token" : 1000000000000004223
          }
        } ]
      },
      "consoleOutput" : "Recomputed user:a9885c61-c442-42d8-af34-8182a8653e3c(Jack)\n"
    },
    "result" : {
      "operation" : "executeScript",
      "status" : "success",
      "importance" : "normal",
      "start" : "2024-02-19T12:05:26.366+01:00",
      "end" : "2024-02-19T12:05:26.393+01:00",
      "microseconds" : 26863,
      "invocationId" : 17478,
      "token" : 1000000000000004219,
      "partialResults" : [ {} ]
    }
  }
}