001/**
002 * Copyright 2005-2016 The Kuali Foundation
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.kuali.rice.kew.impl.peopleflow;
017
018import org.apache.commons.collections.CollectionUtils;
019import org.apache.commons.lang.StringUtils;
020import org.kuali.rice.core.api.CoreConstants;
021import org.kuali.rice.core.api.config.ConfigurationException;
022import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
023import org.kuali.rice.core.api.exception.RiceIllegalStateException;
024import org.kuali.rice.core.api.membership.MemberType;
025import org.kuali.rice.core.api.util.VersionHelper;
026import org.kuali.rice.kew.actionrequest.ActionRequestFactory;
027import org.kuali.rice.kew.actionrequest.ActionRequestValue;
028import org.kuali.rice.kew.actionrequest.KimGroupRecipient;
029import org.kuali.rice.kew.actionrequest.KimPrincipalRecipient;
030import org.kuali.rice.kew.actionrequest.Recipient;
031import org.kuali.rice.kew.api.action.ActionRequestPolicy;
032import org.kuali.rice.kew.api.action.ActionRequestType;
033import org.kuali.rice.kew.api.action.RecipientType;
034import org.kuali.rice.kew.api.document.Document;
035import org.kuali.rice.kew.api.document.DocumentContent;
036import org.kuali.rice.kew.api.peopleflow.PeopleFlowDefinition;
037import org.kuali.rice.kew.api.peopleflow.PeopleFlowDelegate;
038import org.kuali.rice.kew.api.peopleflow.PeopleFlowMember;
039import org.kuali.rice.kew.api.repository.type.KewTypeDefinition;
040import org.kuali.rice.kew.api.repository.type.KewTypeRepositoryService;
041import org.kuali.rice.kew.engine.RouteContext;
042import org.kuali.rice.kew.framework.peopleflow.PeopleFlowTypeService;
043import org.kuali.rice.kew.routeheader.DocumentRouteHeaderValue;
044import org.kuali.rice.kew.routeheader.DocumentRouteHeaderValueContent;
045import org.kuali.rice.kim.api.group.Group;
046import org.kuali.rice.kim.api.identity.principal.Principal;
047import org.kuali.rice.kim.api.role.Role;
048import org.kuali.rice.kim.api.role.RoleMembership;
049import org.kuali.rice.kim.api.role.RoleService;
050import org.kuali.rice.kim.api.services.KimApiServiceLocator;
051import org.kuali.rice.ksb.api.KsbApiServiceLocator;
052import org.kuali.rice.ksb.api.bus.Endpoint;
053
054import javax.xml.namespace.QName;
055import java.util.ArrayList;
056import java.util.Collections;
057import java.util.List;
058import java.util.Map;
059
060/**
061 * Reference implementation of the {@code PeopleFlowRequestGenerator} which is responsible for generating Action
062 * Requests from a {@link PeopleFlowDefinition}.
063 *
064 * @author Kuali Rice Team (rice.collab@kuali.org)
065 */
066public class PeopleFlowRequestGeneratorImpl implements PeopleFlowRequestGenerator {
067
068    private KewTypeRepositoryService typeRepositoryService;
069    private RoleService roleService;
070
071    @Override
072    public List<ActionRequestValue> generateRequests(RouteContext routeContext, PeopleFlowDefinition peopleFlow, ActionRequestType actionRequested) {
073        Context context = new Context(routeContext, peopleFlow, actionRequested);
074        for (PeopleFlowMember member : peopleFlow.getMembers()) {
075            generateRequestForMember(context, member);
076        }
077
078        return context.getActionRequestFactory().getRequestGraphs();
079    }
080
081    protected void generateRequestForMember(Context context, PeopleFlowMember member) {
082        // used later for generating any delegate requests
083        List<ActionRequestValue> memberRequests = new ArrayList<ActionRequestValue>();
084
085        if (MemberType.ROLE == member.getMemberType()) {
086            memberRequests.addAll(findNonRoleRequests(generateRequestsForRoleMember(context, member)));
087        } else {
088            ActionRequestValue actionRequest = context.getActionRequestFactory().addRootActionRequest(
089                    context.getActionRequested().getCode(), member.getPriority(), toRecipient(member), "",
090                    member.getResponsibilityId(), Boolean.TRUE, getActionRequestPolicyCode(member), null);
091
092            if (actionRequest != null) {
093                memberRequests.add(actionRequest);
094            }
095        }
096
097        // KULRICE-5726: Add support for delegates on roles in PeopleFlows as well as using roles as delegates
098        generateDelegationRequests(context, memberRequests, member);
099    }
100
101    /**
102     * generates requests for a PeopleFlow member of type Role.
103     *
104     * <p>Will resolve role qualifiers through the appropriate PeopleFlowTypeService, and if multiple qualifier maps are
105     * generated, it can generate multiple request trees.
106     * parent requests</p>
107     *
108     * @param context the context for request generation
109     * @param member the PeopleFlow member, which is assumed to be of MemberType ROLE
110     * @return a list of root action requests that were generated, or an empty list if no role members were resolved
111     */
112    protected List<ActionRequestValue> generateRequestsForRoleMember(Context context, PeopleFlowMember member) {
113        List<ActionRequestValue> roleMemberRequests = new ArrayList<ActionRequestValue>(); // results
114
115        List<Map<String, String>> roleQualifierMaps = loadRoleQualifiers(context, member.getMemberId());
116        Role role = getRoleService().getRole(member.getMemberId());
117
118        boolean hasPeopleFlowDelegates = !CollectionUtils.isEmpty(member.getDelegates());
119
120        if (role == null) {
121            throw new IllegalStateException("Failed to locate a role with the given role id of '" +
122                    member.getMemberId() + "'");
123        }
124
125        if (CollectionUtils.isEmpty(roleQualifierMaps)) {
126            ActionRequestValue request = addKimRoleRequest(context, member, role, Collections.<String, String>emptyMap(),
127                    hasPeopleFlowDelegates);
128
129            if (request != null) {
130                roleMemberRequests.add(request);
131            }
132        } else {
133            // we may have multiple maps of role qualifiers, so we'll add a request for each map
134            for (Map<String, String> roleQualifiers : roleQualifierMaps) {
135                ActionRequestValue request = addKimRoleRequest(context, member, role, roleQualifiers,
136                        hasPeopleFlowDelegates);
137
138                if (request != null) {
139                    roleMemberRequests.add(request);
140                }
141            }
142        }
143
144        return roleMemberRequests;
145    }
146
147    /**
148     * Uses the ActionRequestFactory to build the request tree for the role members.
149     *
150     * <p>The role members themselves are derived here using the given qualifiers.</p>
151     *
152     * @param context the context for request generation
153     * @param member the PeopleFlow member
154     * @param role the role specified within the member
155     * @param roleQualifiers the qualifiers to use for role member selection
156     * @param ignoreKimDelegates should KIM delegates be ignored when generating requests?
157     * @return the root request of the generated action request tree, or null if no members are found
158     */
159    private ActionRequestValue addKimRoleRequest(Context context, PeopleFlowMember member, Role role,
160            Map<String, String> roleQualifiers, boolean ignoreKimDelegates) {
161
162        ActionRequestValue roleMemberRequest = null;
163
164        List<RoleMembership> memberships = getRoleService().getRoleMembers(Collections.singletonList(
165                member.getMemberId()), roleQualifiers);
166
167        String actionRequestPolicyCode = getActionRequestPolicyCode(member);
168
169        if (!CollectionUtils.isEmpty(memberships)) {
170            roleMemberRequest = context.getActionRequestFactory().addKimRoleRequest(
171                    context.getActionRequested().getCode(), member.getPriority(), role, memberships, null,
172                    member.getResponsibilityId(), true, actionRequestPolicyCode, null, ignoreKimDelegates);
173        }
174
175        return roleMemberRequest;
176    }
177
178    /**
179     * Generates any needed requests for {@link PeopleFlowDelegate}s on the given member.
180     *
181     * <p>If there are no delegates, or if no requests were generated for the member, then this will be a no-op.</p>
182     *
183     * @param context the context for request generation
184     * @param memberRequests any action requests that were generated for the given member
185     * @param member the PeopleFlow member
186     */
187    private void generateDelegationRequests(Context context, List<ActionRequestValue> memberRequests,
188            PeopleFlowMember member) {
189
190        if (CollectionUtils.isEmpty(member.getDelegates()) || CollectionUtils.isEmpty(memberRequests)) {
191            return;
192        }
193
194        for (PeopleFlowDelegate delegate : member.getDelegates()) {
195            for (ActionRequestValue memberRequest : memberRequests) {
196                if (MemberType.ROLE == delegate.getMemberType()) {
197                    generateDelegationToRoleRequests(context, memberRequest, member, delegate);
198                } else {
199                    generateDelegationToNonRoleRequest(context, memberRequest, member, delegate);
200                }
201            }
202        }
203    }
204
205    /**
206     * Uses the ActionRequestFactory to add the delegate request to the given parent request.
207     *
208     * <p>Only handles non-role delegates.  If a delegate of type role is passed, a RiceIllegalStateException will be
209     * thrown.</p>
210     *
211     * @param context the context for request generation
212     * @param memberRequest an action request that was generated for the given member
213     * @param member the PeopleFlow member
214     * @param delegate the delegate to generate a request to
215     */
216    private void generateDelegationToNonRoleRequest(Context context, ActionRequestValue memberRequest,
217            PeopleFlowMember member, PeopleFlowDelegate delegate) {
218
219        Recipient recipient;
220
221        if (MemberType.PRINCIPAL == delegate.getMemberType()) {
222            recipient = new KimPrincipalRecipient(delegate.getMemberId());
223        } else if (MemberType.GROUP == delegate.getMemberType()) {
224            recipient = new KimGroupRecipient(delegate.getMemberId());
225        } else {
226            throw new RiceIllegalStateException("MemberType unknown: " + delegate.getMemberType());
227        }
228
229        String actionRequestPolicyCode = getDelegateActionRequestPolicyCode(member, delegate);
230
231        String delegationAnnotation = generateDelegationAnnotation(memberRequest, member, delegate);
232
233        context.getActionRequestFactory().addDelegationRequest(memberRequest, recipient,
234                delegate.getResponsibilityId(), memberRequest.getForceAction(),
235                delegate.getDelegationType(), actionRequestPolicyCode, delegationAnnotation, null);
236    }
237
238    /**
239     * Builds the String that will be used for the annotation on the delegate requests
240     *
241     * @param parentRequest an action request that was generated for the given member
242     * @param member the PeopleFlow member
243     * @param delegate the delegate
244     * @return the annotation string
245     */
246    private String generateDelegationAnnotation(ActionRequestValue parentRequest, PeopleFlowMember member,
247            PeopleFlowDelegate delegate) {
248
249        StringBuffer annotation = new StringBuffer( "Delegation of: " );
250        annotation.append( parentRequest.getAnnotation() );
251        annotation.append( " to " );
252
253        if (delegate.getMemberType() == MemberType.PRINCIPAL) {
254            annotation.append( "principal " );
255            Principal principal = KimApiServiceLocator.getIdentityService().getPrincipal(delegate.getMemberId());
256
257            if ( principal != null ) {
258                annotation.append( principal.getPrincipalName() );
259            } else {
260                annotation.append( member.getMemberId() );
261            }
262        } else if (delegate.getMemberType() == MemberType.GROUP) {
263            annotation.append( "group " );
264            Group group = KimApiServiceLocator.getGroupService().getGroup(delegate.getMemberId());
265
266            if ( group != null ) {
267                annotation.append( group.getNamespaceCode() ).append( '/' ).append( group.getName() );
268            } else {
269                annotation.append( member.getMemberId() );
270            }
271        } else {
272            annotation.append( "?????? '" );
273            annotation.append( member.getMemberId() );
274            annotation.append( "'" );
275        }
276
277        return annotation.toString();
278    }
279
280
281    /**
282     * Generates any needed requests for the given {@link PeopleFlowDelegate}.
283     *
284     * <p>It is assumed that the given member has the given delegate configured.</p>
285     *
286     * @param context the context for request generation
287     * @param parentRequest an action request that was generated for the given member
288     * @param member the PeopleFlow member, which should contain the given delegate
289     * @param delegate the delegate, assumed to be of MemberType ROLE, to generate a request to
290     */
291    protected void generateDelegationToRoleRequests(Context context,
292            ActionRequestValue parentRequest, PeopleFlowMember member, PeopleFlowDelegate delegate) {
293
294        List<Map<String, String>> roleQualifierList = loadRoleQualifiers(context, delegate.getMemberId());
295        Role role = getRoleService().getRole(delegate.getMemberId());
296
297        if (role == null) {
298            throw new IllegalStateException("Failed to locate a role with the given role id of '" +
299                    delegate.getMemberId() + "'");
300        }
301
302        if (CollectionUtils.isEmpty(roleQualifierList)) {
303            addKimRoleDelegateRequest(context, parentRequest, member, delegate, role,
304                    Collections.<String, String>emptyMap());
305        } else {
306            for (Map<String, String> roleQualifiers : roleQualifierList) {
307                addKimRoleDelegateRequest(context, parentRequest, member, delegate, role, roleQualifiers);
308            }
309        }
310    }
311
312    /**
313     * Helper method uses the ActionRequestFactory to add to the parent request the delegation request(s) to a role.
314     *
315     * <p>The role members themselves are derived here using the given qualifiers.</p>
316     *
317     * @param context the context for request generation
318     * @param parentRequest an action request that was generated for the given member
319     * @param member the PeopleFlow member
320     * @param delegate the delegate to generate a request to
321     * @param role the role specified within the delegate
322     * @param roleQualifiers the qualifiers to use for role member selection
323     */
324    private void addKimRoleDelegateRequest(Context context, ActionRequestValue parentRequest,
325            PeopleFlowMember member, PeopleFlowDelegate delegate, Role role, Map<String, String> roleQualifiers) {
326
327        // sanity check
328        if (delegate.getMemberType() != MemberType.ROLE) {
329            throw new RiceIllegalArgumentException("delegate's member type must be ROLE");
330        } else if (!delegate.getMemberId().equals(role.getId())) {
331            throw new RiceIllegalArgumentException("delegate's member id must match the given role's id");
332        }
333
334        String actionRequestPolicyCode = getDelegateActionRequestPolicyCode(member, delegate);
335
336        List<RoleMembership> memberships = getRoleService().getRoleMembers(Collections.singletonList(
337                delegate.getMemberId()), roleQualifiers);
338
339        if (!CollectionUtils.isEmpty(memberships)) {
340            context.getActionRequestFactory().addDelegateKimRoleRequest(parentRequest,
341                    delegate.getDelegationType(), context.getActionRequested().getCode(), member.getPriority(), role,
342                    memberships, null, delegate.getResponsibilityId(), true, actionRequestPolicyCode, null);
343        }
344    }
345
346    /**
347     * Uses the appropriate {@link PeopleFlowTypeService} to get the role qualifier maps for the given document and
348     * role.
349     *
350     * <p>Note that the PeopleFlowTypeService is selected based on the type id of the PeopleFlow.</p>
351     *
352     * @param context the context for request generation
353     * @param roleId the ID of the role for whom qualifiers are being loaded
354     * @return the qualifier maps, or an empty list if there are none
355     */
356    protected List<Map<String, String>> loadRoleQualifiers(Context context, String roleId) {
357        PeopleFlowTypeService peopleFlowTypeService = context.getPeopleFlowTypeService();
358        List<Map<String, String>> roleQualifierList = new ArrayList<Map<String, String>>();
359
360        if (peopleFlowTypeService != null) {
361            Document document = DocumentRouteHeaderValue.to(context.getRouteContext().getDocument());
362            DocumentRouteHeaderValueContent content = new DocumentRouteHeaderValueContent(document.getDocumentId());
363            content.setDocumentContent(context.getRouteContext().getDocumentContent().getDocContent());
364            DocumentContent documentContent = DocumentRouteHeaderValueContent.to(content);
365
366            Map<String, String> roleQualifiers = peopleFlowTypeService.resolveRoleQualifiers(
367                    context.getPeopleFlow().getTypeId(), roleId, document, documentContent
368            );
369
370            if (roleQualifiers != null) {
371                roleQualifierList.add(roleQualifiers);
372            }
373
374            boolean versionOk = VersionHelper.compareVersion(context.getPeopleFlowTypeServiceVersion(), CoreConstants.Versions.VERSION_2_3_0) != -1;
375            if(versionOk) {
376                List<Map<String, String>> multipleRoleQualifiers = peopleFlowTypeService.resolveMultipleRoleQualifiers(
377                        context.getPeopleFlow().getTypeId(), roleId, document, documentContent);
378
379                if (multipleRoleQualifiers != null) {
380                    roleQualifierList.addAll(multipleRoleQualifiers);
381                }
382            }
383
384        }
385
386        return roleQualifierList;
387    }
388
389    /**
390     * Gets the action request policy code for the given delegate.
391     *
392     * <p>the delegate is considered first, and the member is used as a fallback.  May return null.</p>
393     *
394     * @param member the PeopleFlow member
395     * @param delegate the delegate
396     * @return the action request policy code, or null if none is found
397     */
398    private String getDelegateActionRequestPolicyCode(PeopleFlowMember member, PeopleFlowDelegate delegate) {
399        ActionRequestPolicy actionRequestPolicy = delegate.getActionRequestPolicy();
400
401        return (actionRequestPolicy != null) ? actionRequestPolicy.getCode() : getActionRequestPolicyCode(member);
402    }
403
404    /**
405     * Gets the action request policy code for the given member.
406     *
407     * @param member the PeopleFlow member
408     * @return the action request policy code, or null if none is found
409     */
410    private String getActionRequestPolicyCode(PeopleFlowMember member) {
411        ActionRequestPolicy actionRequestPolicy = member.getActionRequestPolicy();
412
413        return (actionRequestPolicy != null) ? actionRequestPolicy.getCode() : null;
414    }
415
416    private Recipient toRecipient(PeopleFlowMember member) {
417        Recipient recipient;
418        if (MemberType.PRINCIPAL == member.getMemberType()) {
419            recipient = new KimPrincipalRecipient(member.getMemberId());
420        } else if (MemberType.GROUP == member.getMemberType()) {
421            recipient = new KimGroupRecipient(member.getMemberId());
422        } else {
423            throw new IllegalStateException("encountered a member type which I did not understand: " +
424                    member.getMemberType());
425        }
426        return recipient;
427    }
428
429    private Recipient toRecipient(PeopleFlowDelegate delegate) {
430        Recipient recipient;
431        if (MemberType.PRINCIPAL == delegate.getMemberType()) {
432            recipient = new KimPrincipalRecipient(delegate.getMemberId());
433        } else if (MemberType.GROUP == delegate.getMemberType()) {
434            recipient = new KimGroupRecipient(delegate.getMemberId());
435        } else {
436            throw new IllegalStateException("encountered a delegate member type which I did not understand: " +
437                    delegate.getMemberType());
438        }
439        return recipient;
440    }
441
442    public KewTypeRepositoryService getTypeRepositoryService() {
443        return typeRepositoryService;
444    }
445
446    public void setTypeRepositoryService(KewTypeRepositoryService typeRepositoryService) {
447        this.typeRepositoryService = typeRepositoryService;
448    }
449
450    public RoleService getRoleService() {
451        return roleService;
452    }
453
454    public void setRoleService(RoleService roleService) {
455        this.roleService = roleService;
456    }
457
458    /**
459     * Recursively find all non-delegate Group and Principal requests from all of the requests in the given list.
460     *
461     * @param actionRequestValues the list of {@link ActionRequestValue}s to search
462     * @return a list of the non-delegate Group and Principal requests found
463     */
464    private List<ActionRequestValue> findNonRoleRequests(List<ActionRequestValue> actionRequestValues) {
465        List<ActionRequestValue> nonRoleRequests = new ArrayList<ActionRequestValue>();
466
467        return findNonRoleRequests(actionRequestValues, nonRoleRequests);
468    }
469
470    // Recursion helper method
471    private List<ActionRequestValue> findNonRoleRequests(List<ActionRequestValue> actionRequestValues,
472            List<ActionRequestValue> nonRoleRequests) {
473
474        if (!CollectionUtils.isEmpty(actionRequestValues)) {
475            for (ActionRequestValue request : actionRequestValues) if (request.getDelegationType() == null) {
476                if (!CollectionUtils.isEmpty(request.getChildrenRequests())) {
477                    findNonRoleRequests(request.getChildrenRequests(), nonRoleRequests);
478                } else  {
479                    // see if we have a principal request
480                    if (RecipientType.ROLE.getCode() != request.getRecipientTypeCd()) {
481                        nonRoleRequests.add(request);
482                    }
483                }
484            }
485        }
486
487        return nonRoleRequests;
488    }
489
490
491    /**
492     * A simple class used to hold context during the PeopleFlow action request generation process.  Construction of
493     * the context will validate that the given values are valid, non-null values where appropriate.
494     */
495    final class Context {
496
497        private final RouteContext routeContext;
498        private final PeopleFlowDefinition peopleFlow;
499        private final ActionRequestType actionRequested;
500        private final ActionRequestFactory actionRequestFactory;
501
502        // lazily loaded
503        private PeopleFlowTypeService peopleFlowTypeService;
504        private boolean peopleFlowTypeServiceLoaded = false;
505        private String peopleFlowTypeServiceVersion;
506
507        Context(RouteContext routeContext, PeopleFlowDefinition peopleFlow, ActionRequestType actionRequested) {
508            if (routeContext == null) {
509                throw new IllegalArgumentException("routeContext was null");
510            }
511            if (peopleFlow == null) {
512                throw new IllegalArgumentException("peopleFlow was null");
513            }
514            if (!peopleFlow.isActive()) {
515                throw new ConfigurationException("Attempted to route to a PeopleFlow that is not active! " + peopleFlow);
516            }
517            if (actionRequested == null) {
518                actionRequested = ActionRequestType.APPROVE;
519            }
520            this.routeContext = routeContext;
521            this.peopleFlow = peopleFlow;
522            this.actionRequested = actionRequested;
523            this.actionRequestFactory = new ActionRequestFactory(routeContext);
524        }
525
526        RouteContext getRouteContext() {
527            return routeContext;
528        }
529
530        PeopleFlowDefinition getPeopleFlow() {
531            return peopleFlow;
532        }
533
534        ActionRequestType getActionRequested() {
535            return actionRequested;
536        }
537
538        ActionRequestFactory getActionRequestFactory() {
539            return actionRequestFactory;
540        }
541
542        /**
543         * Lazily loads and caches the {@code PeopleFlowTypeService} (if necessary) and returns it.
544         */
545        PeopleFlowTypeService getPeopleFlowTypeService() {
546            if (peopleFlowTypeServiceLoaded) {
547                return this.peopleFlowTypeService;
548            }
549
550            if (getPeopleFlow().getTypeId() != null) {
551                KewTypeDefinition typeDefinition = getTypeRepositoryService().getTypeById(getPeopleFlow().getTypeId());
552
553                if (typeDefinition == null) {
554                    throw new IllegalStateException("Failed to locate a PeopleFlow type for the given type id of '" + getPeopleFlow().getTypeId() + "'");
555                }
556
557                if (StringUtils.isNotBlank(typeDefinition.getServiceName())) {
558                    Endpoint endpoint = KsbApiServiceLocator.getServiceBus().getEndpoint(QName.valueOf(typeDefinition.getServiceName()));
559
560                    if (endpoint == null) {
561                        throw new IllegalStateException("Failed to load the PeopleFlowTypeService with the name '" + typeDefinition.getServiceName() + "'");
562                    }
563
564                    this.peopleFlowTypeService = (PeopleFlowTypeService)endpoint.getService();
565                    this.peopleFlowTypeServiceVersion = endpoint.getServiceConfiguration().getServiceVersion();
566                }
567            }
568            peopleFlowTypeServiceLoaded = true;
569            return this.peopleFlowTypeService;
570        }
571
572        String getPeopleFlowTypeServiceVersion() {
573            if (!this.peopleFlowTypeServiceLoaded) {
574                // execute getPeopleFlowTypeService first to lazy load
575                getPeopleFlowTypeService();
576            }
577
578            return this.peopleFlowTypeServiceVersion;
579        }
580    }
581}