createRoles

Purpose

This operation creates multiple new roles in PPM Center.

Function and Parameters

This operation returns zero or more role reference objects from PPM Center according to a list of (maximum 1,000) role beans to create roles. The user performing this operation must have the following access grant:

• Edit All Roles

Required Fields:

• Name

• Enabled

Optional Fields:

• Description

• ID

Limitations

This operation has the following limitations:

• Maximum 1,000 roles can be created in a single invocation.

• Creation of new roles using this operation occurs in a single transaction and as an atomic operation. If the creation of one role fails, the whole operation is rolled back.

Input

An array of Role.

Return

An array of RoleReference.

Java Interface

CreateRolesResponseDocument createRoles(CreateRolesDocument in)

Parameters	Description
CreateRolesDocument	Wrapper array of role bean. (RoleBean[])
CreateRolesResponseDocument	Wrapper for the roles reference array. (RoleReference[])

Java Examples

Example: create new roles.

public static void main(String[] args) throws Exception {
      // check parameter
         if (args.length < 1) {
             System.out.println("Usage: java
ResourceServiceClient <service URL> [<true/false>]");
            System.exit(1);
        }

        System.out.println("Starting Resource Service
tests...");
        ResourceServiceClient rm = new ResourceServiceClient();
        rm.WSURL = args[0];
       if (args.length > 1 && args[1].equalsIgnoreCase("true"))
{
             rm.DEBUG = true;
       }

       System.out.println("Test create role ...");
            Role role = Role.Factory.newInstance();
              role.setName("Test Role " +
System.currentTimeMillis());
                role.setDescription("New Role");
                role.setEnabled(true);
             RoleReference[] roleReferences = createRoles(new
Role[]{role});

        System.out.println("Resource Service tests complete.");
   }
   RoleReference[] createRoles(Role[] roles) throws Exception {
         ResourceServiceStub service = new
ResourceServiceStub(ctx, RESOURCE_SERVICE);
         CreateRolesDocument createRolesDoc =
CreateRolesDocument.Factory.newInstance();
         createRolesDoc.addNewCreateRoles().setRoleArray(roles);
         CreateRolesResponseDocument responseDocCreate =
service.createRoles(createRolesDoc);
         CreateRolesResponse responseCreate =
responseDocCreate.getCreateRolesResponse();
        debugPrint(responseCreate, "create response");
        return responseCreate.getRoleRefArray();
    }

Errors and Exceptions

When an error occurs on this operation, you will see a description of the root cause in the log or in the response message.

The server log file content is similar to the following:

Exception in thread "main" org.apache.axis2.AxisFault:
<exception:exceptionDetails xmlns:exception="http://
www.mercury.com/ppm/ws/exception">
<exception:detail>[root cause description] </exception:detail>
</exception:exceptionDetails>

Possible root cause descriptions:

Message Code	Message	Cause(s)	Possible Corrective Action
error.ws.maxRoles	The maximum number of roles to process in a single web service transaction may not exceed 1000.	The role list has more than 1,000 roles.	Break up the list into smaller chunks and process over multiple transactions.
error.duplicateName	A role with the name "{0}" already exists. Enter a different name.	The role already exists.	Enter a different name.
error.ws.nameRequiredRole	Name cannot be blank. Provide a name for each role.	At least one of the roles does not have a name.	Ensure all roles have a name.
error.ws.descriptionTooLong	Description cannot be longer than 650 characters.	The description of a role is more than 650 characters.	Reduce length of description.
error.ws.nameTooLong	Name cannot be longer than 260 characters.	The name of a role is great than 260.	Reduce length of name.