---
title: Register custom scripted actions
description: You can register custom scripts that initiate an action on a managed object endpoint. You can declare any number of actions in your managed object schema and associate those actions with a script.
component: pingoneaic
page_id: pingoneaic:idm-scripting:custom-scripted-actions
canonical_url: https://docs.pingidentity.com/pingoneaic/idm-scripting/custom-scripted-actions.html
section_ids:
  example_scenario: Example scenario
---

# Register custom scripted actions

You can register custom scripts that initiate an action on a managed object endpoint. You can declare any number of actions in your managed object schema and associate those actions with a script.

The return value of a custom scripted action is ignored. The managed object is returned as the response of the scripted action, whether that object has been updated by the script or not.

Custom scripted actions have access to the following variables:

* `context`

* `request`

* `resourcePath`

* `object`

## Example scenario

In this scenario, you want your managed users to have the option to receive update notifications. You can define an *action* that toggles the value of a specific property on the user object.

1. Add an `updates` property to the managed object configuration *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint.)*:

   |   |                                                                                                                                                                                                                                                                                                                                                                                  |
   | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   |   | The property `updates` is used for readability in the following example. In IDM you do not extend the default IDM managed object schema. Instead, you use one of the generic extension attributes. For more information, refer to [General purpose extension attributes](../identities/user-identity-properties-attributes-reference.html#general-purpose-extension-attributes). |

   ```json
   "properties": {
       ...
       "updates": {
           "title": "Automatic Updates",
           "viewable": true,
           "type": "boolean",
           "searchable": true,
           "userEditable": true
       },
       ...
   }
   ```

2. Add a `toggleUpdates` action to the managed user object definition:

   ```json
   {
       "objects" : [
           {
               "name" : "user",
               "onCreate" : {
                   ...
               },
               ...
               "actions" : {
                   "toggleUpdates" : {
                       "type" : "text/javascript",
                       "source" : "openidm.patch(resourcePath, null, [{ 'operation' : 'replace', 'field' : '/updates', 'value' : !object.updates }])"
                   }
               },
               ...
           }
       ]
   }
   ```

   |   |                                                                                                    |
   | - | -------------------------------------------------------------------------------------------------- |
   |   | The `toggleUpdates` action calls a script that changes the value of the user's `updates` property. |

3. To call the script, specify the ID of the action in a POST request on the user object:

   ```
   curl \
   --header "Authorization: Bearer <access-token>" \
   --header "Accept-API-Version: resource=1.0" \
   --request POST \
   "https://<tenant-env-fqdn>/openidm/managed/realm-name_user/ID?_action=toggleUpdates"
   ```

   You can now test the functionality.

4. Create a managed user, `bjensen`, with an `updates` property set to `true`:

   ```
   curl \
   --header "Authorization: Bearer <access-token>" \
   --header "Accept-API-Version: resource=1.0" \
   --header "Content-Type: application/json" \
   --request POST \
   --data '{
     "userName":"bjensen",
     "sn":"Jensen",
     "givenName":"Barbara",
     "mail":"bjensen@example.com",
     "telephoneNumber":"5556787",
     "description":"Created by OpenIDM REST.",
     "updates": true,
     "password":"Passw0rd"
   }' \
   "https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_action=create"
   {
     "_id": "9dce06d4-2fc1-4830-a92b-bd35c2f6bcbb",
     "_rev": "0000000050c62938",
     "userName": "bjensen",
     "sn": "Jensen",
     "givenName": "Barbara",
     "mail": "bjensen@example.com",
     "telephoneNumber": "5556787",
     "description": "Created by OpenIDM REST.",
     "updates": true,
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }
   ```

5. Run the `toggleUpdates` action on `bjensen`:

   ```
   curl \
   --header "Authorization: Bearer <access-token>" \
   --header "Accept-API-Version: resource=1.0" \
   --request POST \
   "https://<tenant-env-fqdn>/openidm/managed/realm-name_user/9dce06d4-2fc1-4830-a92b-bd35c2f6bcbb?_action=toggleUpdates"
   {
     "_id": "9dce06d4-2fc1-4830-a92b-bd35c2f6bcbb",
     "_rev": "00000000a92657c7",
     "userName": "bjensen",
     "sn": "Jensen",
     "givenName": "Barbara",
     "mail": "bjensen@example.com",
     "telephoneNumber": "5556787",
     "description": "Created by OpenIDM REST.",
     "updates": false,
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }
   ```

   |   |                                                           |
   | - | --------------------------------------------------------- |
   |   | This action sets bjensen's `updates` property to `false`. |