wfobjs.py 14.6 KB
Newer Older
Adrien Di Mascio's avatar
Adrien Di Mascio committed
1
2
3
"""workflow definition and history related entities

:organization: Logilab
4
:copyright: 2001-2009 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
Adrien Di Mascio's avatar
Adrien Di Mascio committed
5
:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
6
:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses
Adrien Di Mascio's avatar
Adrien Di Mascio committed
7
8
9
"""
__docformat__ = "restructuredtext en"

10
11
from warnings import warn

12
from logilab.common.decorators import cached, clear_cache
13
14
from logilab.common.deprecation import deprecated

Adrien Di Mascio's avatar
Adrien Di Mascio committed
15
from cubicweb.entities import AnyEntity, fetch_config
16
17
18
19
20
21
22
23
24
25
from cubicweb.interfaces import IWorkflowable
from cubicweb.common.mixins import MI_REL_TRIGGERS


class Workflow(AnyEntity):
    id = 'Workflow'

    @property
    def initial(self):
        """return the initial state for this workflow"""
26
        return self.initial_state and self.initial_state[0] or None
27
28
29
30
31

    def is_default_workflow_of(self, etype):
        """return True if this workflow is the default workflow for the given
        entity type
        """
32
33
        return any(et for et in self.reverse_default_workflow
                   if et.name == etype)
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

    def after_deletion_path(self):
        """return (path, parameters) which should be used as redirect
        information when this entity is being deleted
        """
        if self.workflow_of:
            return self.workflow_of[0].rest_path(), {'vid': 'workflow'}
        return super(Workflow, self).after_deletion_path()

    # state / transitions accessors ############################################

    def state_by_name(self, statename):
        rset = self.req.execute('Any S, SN WHERE S name SN, S name %(n)s, '
                                'S state_of WF, WF eid %(wf)s',
                                {'n': statename, 'wf': self.eid}, 'wf')
        if rset:
            return rset.get_entity(0, 0)
        return None

    def state_by_eid(self, eid):
        rset = self.req.execute('Any S, SN WHERE S name SN, S eid %(s)s, '
                                'S state_of WF, WF eid %(wf)s',
                                {'s': eid, 'wf': self.eid}, ('wf', 's'))
        if rset:
            return rset.get_entity(0, 0)
        return None

    def transition_by_name(self, trname):
        rset = self.req.execute('Any T, TN WHERE T name TN, T name %(n)s, '
                                'T transition_of WF, WF eid %(wf)s',
                                {'n': trname, 'wf': self.eid}, 'wf')
        if rset:
            return rset.get_entity(0, 0)
        return None

    def transition_by_eid(self, eid):
        rset = self.req.execute('Any T, TN WHERE T name TN, T eid %(t)s, '
                                'T transition_of WF, WF eid %(wf)s',
                                {'t': eid, 'wf': self.eid}, ('wf', 't'))
        if rset:
            return rset.get_entity(0, 0)
        return None

    # wf construction methods ##################################################
Adrien Di Mascio's avatar
Adrien Di Mascio committed
78

79
80
81
82
    def add_state(self, name, initial=False, **kwargs):
        """method to ease workflow definition: add a state for one or more
        entity type(s)
        """
83
        state = self.req.create_entity('State', name=unicode(name), **kwargs)
84
85
86
87
88
89
90
91
92
93
94
95
96
97
        self.req.execute('SET S state_of WF WHERE S eid %(s)s, WF eid %(wf)s',
                         {'s': state.eid, 'wf': self.eid}, ('s', 'wf'))
        if initial:
            assert not self.initial
            self.req.execute('SET WF initial_state S '
                             'WHERE S eid %(s)s, WF eid %(wf)s',
                             {'s': state.eid, 'wf': self.eid}, ('s', 'wf'))
        return state

    def add_transition(self, name, fromstates, tostate,
                       requiredgroups=(), conditions=(), **kwargs):
        """method to ease workflow definition: add a transition for one or more
        entity type(s), from one or more state and to a single state
        """
98
        tr = self.req.create_entity('Transition', name=unicode(name), **kwargs)
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
        self.req.execute('SET T transition_of WF '
                         'WHERE T eid %(t)s, WF eid %(wf)s',
                         {'t': tr.eid, 'wf': self.eid}, ('t', 'wf'))
        for state in fromstates:
            if hasattr(state, 'eid'):
                state = state.eid
            self.req.execute('SET S allowed_transition T '
                             'WHERE S eid %(s)s, T eid %(t)s',
                             {'s': state, 't': tr.eid}, ('s', 't'))
        if hasattr(tostate, 'eid'):
            tostate = tostate.eid
        self.req.execute('SET T destination_state S '
                         'WHERE S eid %(s)s, T eid %(t)s',
                         {'t': tr.eid, 's': tostate}, ('s', 't'))
        tr.set_transition_permissions(requiredgroups, conditions, reset=False)
        return tr
115

Adrien Di Mascio's avatar
Adrien Di Mascio committed
116

117
118
119
120
121
class BaseTransition(AnyEntity):
    """customized class for abstract transition

    provides a specific may_be_fired method to check if the relation may be
    fired by the logged user
Adrien Di Mascio's avatar
Adrien Di Mascio committed
122
123
124
    """
    id = 'Transition'
    fetch_attrs, fetch_order = fetch_config(['name'])
125

126
127
    def may_be_fired(self, eid):
        """return true if the logged user may fire this transition
Adrien Di Mascio's avatar
Adrien Di Mascio committed
128

129
        `eid` is the eid of the object on which we may fire the transition
Adrien Di Mascio's avatar
Adrien Di Mascio committed
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
        """
        user = self.req.user
        # check user is at least in one of the required groups if any
        groups = frozenset(g.name for g in self.require_group)
        if groups:
            matches = user.matching_groups(groups)
            if matches:
                return matches
            if 'owners' in groups and user.owns(eid):
                return True
        # check one of the rql expression conditions matches if any
        if self.condition:
            for rqlexpr in self.condition:
                if rqlexpr.check_expression(self.req, eid):
                    return True
        if self.condition or groups:
            return False
        return True

    def after_deletion_path(self):
        """return (path, parameters) which should be used as redirect
        information when this entity is being deleted
        """
        if self.transition_of:
154
            return self.transition_of[0].rest_path(), {}
Adrien Di Mascio's avatar
Adrien Di Mascio committed
155
156
        return super(Transition, self).after_deletion_path()

157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
    def set_transition_permissions(self, requiredgroups=(), conditions=(),
                                   reset=True):
        """set or add (if `reset` is False) groups and conditions for this
        transition
        """
        if reset:
            self.req.execute('DELETE T require_group G WHERE T eid %(x)s',
                             {'x': self.eid}, 'x')
            self.req.execute('DELETE T condition R WHERE T eid %(x)s',
                             {'x': self.eid}, 'x')
        for gname in requiredgroups:
            ### XXX ensure gname validity
            rset = self.req.execute('SET T require_group G '
                                    'WHERE T eid %(x)s, G name %(gn)s',
                                    {'x': self.eid, 'gn': gname}, 'x')
            assert rset, '%s is not a known group' % gname
        if isinstance(conditions, basestring):
            conditions = (conditions,)
        for expr in conditions:
            if isinstance(expr, str):
                expr = unicode(expr)
            self.req.execute('INSERT RQLExpression X: X exprtype "ERQLExpression", '
                             'X expression %(expr)s, T condition X '
                             'WHERE T eid %(x)s',
                             {'x': self.eid, 'expr': expr}, 'x')
        # XXX clear caches?
183

Adrien Di Mascio's avatar
Adrien Di Mascio committed
184

185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
class Transition(BaseTransition):
    """customized class for Transition entities"""
    id = 'Transition'

    def destination(self):
        return self.destination_state[0]

    def has_input_state(self, state):
        if hasattr(state, 'eid'):
            state = state.eid
        return any(s for s in self.reverse_allowed_transition if s.eid == state)


class WorkflowTransition(BaseTransition):
    """customized class for WorkflowTransition entities"""
    id = 'WorkflowTransition'

    @property
    def subwf(self):
        return self.subworkflow[0]

    def destination(self):
        return self.subwf.initial


class State(AnyEntity):
    """customized class for State entities"""
Adrien Di Mascio's avatar
Adrien Di Mascio committed
212
213
214
    id = 'State'
    fetch_attrs, fetch_order = fetch_config(['name'])
    rest_attr = 'eid'
215

Adrien Di Mascio's avatar
Adrien Di Mascio committed
216
217
218
219
220
    def after_deletion_path(self):
        """return (path, parameters) which should be used as redirect
        information when this entity is being deleted
        """
        if self.state_of:
221
            return self.state_of[0].rest_path(), {}
Adrien Di Mascio's avatar
Adrien Di Mascio committed
222
223
        return super(State, self).after_deletion_path()

224

Adrien Di Mascio's avatar
Adrien Di Mascio committed
225
226
227
228
229
230
231
232
class TrInfo(AnyEntity):
    """customized class for Transition information entities
    """
    id = 'TrInfo'
    fetch_attrs, fetch_order = fetch_config(['creation_date', 'comment'],
                                            pclass=None) # don't want modification_date
    @property
    def for_entity(self):
233
234
        return self.wf_info_for[0]

Adrien Di Mascio's avatar
Adrien Di Mascio committed
235
236
    @property
    def previous_state(self):
237
        return self.from_state[0]
238

Adrien Di Mascio's avatar
Adrien Di Mascio committed
239
240
241
242
    @property
    def new_state(self):
        return self.to_state[0]

243
244
245
246
    @property
    def transition(self):
        return self.by_transition and self.by_transition[0] or None

Adrien Di Mascio's avatar
Adrien Di Mascio committed
247
248
249
250
251
252
253
    def after_deletion_path(self):
        """return (path, parameters) which should be used as redirect
        information when this entity is being deleted
        """
        if self.for_entity:
            return self.for_entity.rest_path(), {}
        return 'view', {}
254
255
256
257
258
259
260
261
262
263
264
265
266
267


class WorkflowableMixIn(object):
    """base mixin providing workflow helper methods for workflowable entities.
    This mixin will be automatically set on class supporting the 'in_state'
    relation (which implies supporting 'wf_info_for' as well)
    """
    __implements__ = (IWorkflowable,)

    @property
    def current_workflow(self):
        """return current workflow applied to this entity"""
        if self.custom_workflow:
            return self.custom_workflow[0]
268
        return self.cwetype_workflow()
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291

    @property
    def current_state(self):
        """return current state entity"""
        return self.in_state and self.in_state[0] or None

    @property
    def state(self):
        """return current state name"""
        try:
            return self.in_state[0].name
        except IndexError:
            self.warning('entity %s has no state', self)
            return None

    @property
    def printable_state(self):
        """return current state name translated to context's language"""
        state = self.current_state
        if state:
            return self.req._(state.name)
        return u''

292
293
294
295
296
297
298
    @property
    def workflow_history(self):
        """return the workflow history for this entity (eg ordered list of
        TrInfo entities)
        """
        return self.reverse_wf_info_for

299
300
301
302
    def latest_trinfo(self):
        """return the latest transition information for this entity"""
        return self.reverse_wf_info_for[-1]

303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
    @cached
    def cwetype_workflow(self):
        """return the default workflow for entities of this type"""
        # XXX CWEType method
        wfrset = self.req.execute('Any WF WHERE X is ET, X eid %(x)s, '
                                  'WF workflow_of ET', {'x': self.eid}, 'x')
        if len(wfrset) == 1:
            return wfrset.get_entity(0, 0)
        if len(wfrset) > 1:
            for wf in wfrset.entities():
                if wf.is_default_workflow_of(self.id):
                    return wf
            self.warning("can't find default workflow for %s", self.id)
        else:
            self.warning("can't find any workflow for %s", self.id)
        return None

320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
    def possible_transitions(self):
        """generates transition that MAY be fired for the given entity,
        expected to be in this state
        """
        if self.current_state is None or self.current_workflow is None:
            return
        rset = self.req.execute(
            'Any T,N WHERE S allowed_transition T, S eid %(x)s, '
            'T name N, T transition_of WF, WF eid %(wfeid)s',
            {'x': self.current_state.eid,
             'wfeid': self.current_workflow.eid}, 'x')
        for tr in rset.entities():
            if tr.may_be_fired(self.eid):
                yield tr

    def _get_tr_kwargs(self, comment, commentformat):
        kwargs = {}
        if comment is not None:
            kwargs['comment'] = comment
            if commentformat is not None:
                kwargs['comment_format'] = commentformat
        return kwargs

    def fire_transition(self, trname, comment=None, commentformat=None):
        """change the entity's state by firing transition of the given name in
        entity's workflow
        """
        assert self.current_workflow
        tr = self.current_workflow.transition_by_name(trname)
        assert tr is not None, 'not a %s transition: %s' % (self.id, state)
        # XXX try to find matching transition?
        self.req.create_entity('TrInfo', ('by_transition', 'T'),
                               ('wf_info_for', 'E'), T=tr.eid, E=self.eid,
                               **self._get_tr_kwargs(comment, commentformat))

    def change_state(self, statename, comment=None, commentformat=None):
        """change the entity's state to the state of the given name in entity's
        workflow. This method should only by used by manager to fix an entity's
        state when their is no matching transition, otherwise fire_transition
        should be used.
        """
        assert self.current_workflow
        if not isinstance(statename, basestring):
            warn('give a state name')
            state = self.current_workflow.state_by_eid(statename)
            assert state is not None, 'not a %s state: %s' % (self.id, state)
        else:
            state = self.current_workflow.state_by_name(statename)
        # XXX try to find matching transition?
        self.req.create_entity('TrInfo', ('to_state', 'S'),
                               ('wf_info_for', 'E'), S=state.eid, E=self.eid,
                               **self._get_tr_kwargs(comment, commentformat))

373
374
375
376
377

    def clear_all_caches(self):
        super(WorkflowableMixIn, self).clear_all_caches()
        clear_cache(self, 'cwetype_workflow')

378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
    @deprecated('get transition from current workflow and use its may_be_fired method')
    def can_pass_transition(self, trname):
        """return the Transition instance if the current user can fire the
        transition with the given name, else None
        """
        tr = self.current_workflow and self.current_workflow.transition_by_name(trname)
        if tr and tr.may_be_fired(self.eid):
            return tr

    @property
    @deprecated('use printable_state')
    def displayable_state(self):
        return self.req._(self.state)

MI_REL_TRIGGERS[('in_state', 'subject')] = WorkflowableMixIn