Add Action Groups to a Method

You can define multiple action groups, add them to C3 Agentic AI Platform roles, and add them to a Type to grant access to a specific method. This means that if a user has permissions for any of the action groups, they can run the method.

Annotating Type methods with action groups allows you to restrict access to certain methods, implement role-based access control (RBAC), and prevent data tampering or unauthorized changes.

Action group logic works differently with security-leveled roles. Security-leveled roles follow a strict hierarchy and enforce platform-wide access restrictions. For a full explanation of how security levels work and how they affect role behavior, see Security levels in the C3 Agentic AI Platform.

This topic provides examples on how to annotate a Type method and explains how the action group logic works with and without security-level roles.

Copy link to this section

Add action groups to a Type method

Complete the following steps to add action groups to a Type.

Define action groups in JSON files. Name the JSON files to match the action group id field, for example ActionGroup1.json and ActionGroup2.json. Here are examples for ActionGroup1 and ActionGroup2 action groups:

[
  {
    "id": "ActionGroup1"
  }
]

[
  {
    "id": "ActionGroup2"
  }
]

Create the action groups by adding each action group JSON file to the metadata/Action.Group directory. Here's an example of the expected file structure:

package-root/
└── metadata/
    └── Action.Group/
        ├── ActionGroup1.json
        └── ActionGroup2.json

Each file should define exactly one action group. If you need multiple action groups, create separate files for each.

In a role metadata file, define permissions for the action groups by adding an action group to a role's permissions:

{
    "id": "C3.MyTypeRole",
    "description": "This role is used for testing a Basic User",
    "permissions": [
        "allow:MyType:ActionGroup1:"
    ]
}

The permission string allow:MyType:ActionGroup1: allows the C3.MyTypeRole role to run methods annotated with the ActionGroup1 action group.

In a user metadata file, assign the role to a user to grant them access to the actions in the action group:

[
  {
    "id": "MyUser",
    "name": "My User",
    "email": "myuser@c3.ai",
    "c3groups": [
      "C3.MyTypeRole"
    ]
  }
]

Alternatively, you can also assign the role to a user by running the following command in C3 AI Console:

User.make({id: "MyUser"}).addToGroup("C3.MyTypeRole")

In this example, the MyUser user has permissions from the C3.MyTypeRole role and can run methods annotated with the ActionGroup1 action group.

In the Type file, annotate the method you want to add action groups to:

type MyType {
  @action(group=['ActionGroup1', 'ActionGroup2'])
  myFunction: function() js-server
}

In this example, the MyUser user can run this method, because they have the C3.MyTypeRole role with permissions for the ActionGroup1 action group.

Annotating the myFunction method with the @action annotation specifies that users assigned roles with permissions for the ActionGroup1 or ActionGroup2 action groups can run the method. This is an example of using action groups in a Type method with OR logic.

Copy link to this section

Working with security-leveled action groups

When you annotate methods with action groups from security-leveled roles, only users with the security-leveled role can run the method.

The following table lists security-leveled roles and their respective action group id values, as defined in the SecurityLevel Type:

Each security-leveled role has a predefined string for its action group id value. If you annotate a Type method with a security-leveled action group and an action group without a security level, only users with the security-leveled role can run the method.

Here's an example of a method annotated with a security-leveled action group and an action group without a security level:

type MyType {
  @action(group=['ActionGroup1', 'app-admin'])
  myFunction: function() js-server
}

In this example, only users with the C3.AppAdmin role can run the myFunction method, because the C3.AppAdmin role is security-leveled and the ActionGroup1 action group is not.

Copy link to this section

See also

• Security levels in the C3 Agentic AI Platform
• Define Permissions
• Define Roles and Groups